XML Format

Anstatt sofort einen DTD zu definieren (die Dinger kann eh kaum jemand lesen) arbeiten wir hier ein Beispiel-Dokument aus, und diskutieren darüber.

Generelles

Das Format soll es u.a. erlauben, einen Client zu entwickeln der weitestgehend Spiel-agnostisch ist, und trotzdem in der Lage moeglichst viel des Spielstandes fuer den Spieler sichtbar zu machen. Das bedeutet, dass man sich eher auf weniger Elemente festlegt, die ein Client dann jeweils in einer "Default" Implementation behandeln kann.

Die Hierarchie von "echten" Objekten, item, unit, region, alliance, faction, building, ship, usw. wuerde ich trotzdem gern als <item/>, <unit/>, usw. modellieren. Bei Schiffen kann man eventuell auf allgemeine Transporter verallgemeinern, aber fuer alle Objekte gilt, dass sie sich in ihrere Art und ihrere Darstellung stark genug voneinander unterschieden.

Einige Beispiele, wo weniger Elemente besser sind:

<region><resource ref="wood"/></region>

... ist besser als ...

<region><wood/></region>

Weil ein Client, der Ressourcen darstellen kann auch ohne Wissen um die Resource Holz einen Fallback machen kann ("wood" in den Localization-Ressourcen nach Icon + Name durchsuchen) als mit einem <wood/> Element, das er nicht kennt. Mal ganz abgesehen davon, dass jede neue Ressource eine Aenderung am DTD verursacht.

<ship><link rel="captain" ref="unit_546"/></ship>

Hier kann der Regel-agnostische Client immerhin noch das Icon des referenzierten Objektes, seinen Schlüssel und evtl. den Namen, darstellen, selbst wenn er mit dem Begriff "Kapitän" nichts anzufangen weiß. Wenn er es natürlich kennt, kann er spielspezifisch darauf reagieren (und z.B. testen ob der Kapitaen der Schiff-betretenden Einheit ein HELFE setzt, o.ä.

Ein link-Attribut sollte imemr dann verwendet werden, wenn es unwahrscheinlich ist, dass die Beziehung in mehreren Spielen vorkommt. Das attribut "rel" gibt dem Client einen Hinweis darueber, ein welcher Relation das verlinkte Objekt zum parent-Objekt steht, ähnlich wie in HTML.

IDs und Referenzen

• Elemente die wir mit IDs versehen verwenden das standardisierte xml:id Attribut.

Spielobjekte (Regionen, Einheiten, Schiffe, Burgen, ...)

... also Objekte die in Atlantis-ähnlichen Spielen eine id haben. Um diese im Spiel anzusprechen, erhalten sie zusätzlich zur xml:id das Attribut key. Das xml:id Attribut kann, muss aber nicht, den key als Teil der id verwenden.

Beispiele:

<unit xml:id="unit_raLf" key="raLf">...
<ship xml:id="ship_12f4" key="12f4">...
<unit xml:id="ddff556787u" key="enno">...

• Wird der XML-Report vom Server erzeugt, werden die xml:id vom Server vorgegeben.
• Wird der XML-Report aus einem anderen Format konvertiert, welches keine global eindeutigen ids hat (CR), dann sollte der client <elementname>_<key> als xml:id generieren.
• Referenzen auf diese Elemente sollten ein einheitliches Attribut verwenden, z.b. ref

<memberof ref="faction_bgz7"/>

Regelobjekte (Gegenstände, Talente, Resourcen, Rassen, Terrain ...)

... also mögliche Typen die üblicherweise in den Regeln definiert werden. Im Report wird, wenn überhaupt möglich, nur darauf referenziert.

Beispiel in der Regeldatei:

<itemtype xml:id="itemtype_wateroflife">...
<skilltype xml:id="skilltype_perception">...

• Referenzen auf diese "Typ"-Elemente sollten ein einheitliches Attribut verwenden, z.b. type
• Elemente tragen nach Möglichkeit die Bezeichnung ihrer "Rolle". Wobei <item> den Besitz/vorhandensein eines Gegenstandes des Typ <itemtype> meint. Gleiches gilt für <skill>.

<items>
  <item type="itemtype_wateroflife">12</item>
</items>
<skills>
  <skill type="skilltype_perception"><level>12</level></skill>
</skills> 

• ggf. macht es sinn itemtype als item zu bezeichnen und das Halten eines Gegenstandes doch unter einem anderen element abzulegen. (z.b. hasitem) - meinungen gefragt ...

Lokalisierung

• Es sollte das Attribut xml:lang verwendet werden. Elemente die dieses Attribut erlauben, sollten generell auch mehrfach auftauchen dürfen. Problematisch ist der Umgang wenn man mehrfach die gleiche sprache angibt.
• Elemente die so etwas unterstützen könnten:

<name ...>...
<descr ...>...
<text ...>...
<keytext ...>...  
<pattern ...>...

Datierung

Fürs erste haben wir uns gegen eine Datierung von einzelnen Elementen entschieden. Ein Report erhält daher global ein Datum, und gibt den Status zu diesem Datum wieder

Beispiel Report

Komplettbeispiel für Menouthis mit Anmerkungen

Header und Serverinfos
<!DOCTYPE atlantis PUBLIC "-//PBEM//DTD Atlantis 1.0//EN" "http://eressea.de/atlantis-report.dtd"> <?xml version="1.0" encoding="UTF-8"?> <atlantis rules="eressea"> <server> <uri>mailto:eressea-server@eressea.kn-bremen.de</uri> <subject>ERESSEA BEFEHLE</subject> </server>	DTD - machen wir eine DTD für alle Spiele oder gibt es eine Grundlagen-DTD und dann spielspezifische DTD? Version und Encoding Benutztes Regelset
Allianzen
<alliance id="alliance_1245" key="1245">  ??? <helpstatus set="59"/> <helpstatus ref="faction_1234" set="59"/> <helpstatus ref="alliance_badg" set="1"/> </alliance>	Ich würde alliance nicht als Element für die Helfe Stati verwenden sondern für richtige "Parteigruppen" reservieren. Auch sowas soll es ja in Vinyambar schon gegeben haben. d.h. Ein Volk ist dann Teil genau einer (oder mehrerer Allianzen). Möglicherweise ist Allianz auch ein Konstrukt des Clients zur einfacheren Verwaltung der Helfe-Stati.
Parteien
<faction id="faction_Lotr" key="Lotr"> <name>xxxxx</name> <descr>dsfsf sdf sdf</descr> <type role="race" ref="race_aquarians"/> <type role="magic" ref="magic_gwyrrd"/> <type role="culture" ref="culture_mechanics"/> <status type="age">60</status> <status type="points">12345</status> <status type="avgpoints">10000</status> <items> <item type="item_birthdaycake">1</item> </items>	Kultur und Magiegebiet könnten auch Referenzen sein ... to be discussed. Alter, Punkte usw. würde ich gar nicht gesondert erfassen. Parteien können items haben.
Allianzen (HELFE Stati)
<helpstatus ref="faction_1234" set="59"/> <diplomacy ref="faction_1234"> <state type="state_help_silver"/> <state type="state_help_guard"/> <state type="state_help_give"/> <state type="state_help_defend"/> <state type="state_help_attack"/> <state type="state_forbid_trade"/> <state type="state_forbid_recruit"/> <state type="state_warn_nmr"/> <state type="state_send_report"/> </diplomacy>	helpstatus ist denke ich das bessere Element um die aktuelle Eressea Situation für Gruppen und Parteien zu beschreiben. diplomacy wurde von während es Chats erwähnt. Ausserdem sollen Solche Beziehungen zu anderen Völkern allgemeingültiger sein. Auch "Krieg" bzw. "Feind" sollte möglich sein.
Gruppen (wie in Eressea verwendet)
<unitgroup id="unitgroup.1234.Kapitäne"> <helpstatus remove="2"/> <helpstatus ref="faction.gtzu" add="2"/> </unitgroup> <unitgroup id="unitgroup.1234.Matrosen" basegroup="unitgroup.1234.Kapitäne"> <helpstatus remove="1"/> </unitgroup>	Vorsicht, hier muss der eindeutige Key auch den Parteikey enthalten, sonst ist die Gruppe möglicherweise nicht eindeutig. Neben einer einfach Auflistung der Helfestati sollte der client/server erlauben unterschiede zur Partei oder einer anderen Gruppe zu definieren Im angegebenen Beispiel basiert die Gruppe Kapitäne auf der Partei. Allerdings wird der Status 2 für alle entfernt, dann aber wieder für ein Volk gesetzt. Die Matrosen basieren auf den Kapitänen, nur nehmen sie von anderen keine Waren entgegen. Naja so ähnlich jedenfalls sollte es laufen, nicht immer überall alles neu definieren, sondern sozusagen deltas definiert werden können. Wenn es der Server nicht unterstützt, soll der Client entsprechend die Helfe Stati automatisch setzen.
Messages
<message id="message_123456" type="msgtype_23423546"> <text xml:lang="de"> Die Nussschale (1234) segelt von Irgendwo (1,2) nach Nirgendwo (99,99). Dabei wurden Ozean (1,3), Ozean (1,4) ... und Ozean (98,99) durchquert. </text> <attribute name="ship"><shipref ref="ship_1234"/></attribute> <attribute name="from"><regionref ref="region_653456"/></attribute> <attribute name="to"><regionref ref="region_653567"/></attribute> <attribute name="through"> <regionref ref="region_953456"/> <regionref ref="region_68656"/> ... <regionref ref="region_114562"/> </attribute> <message id="message_456346" type="msgtype_456902645"> <text xml:lang="de"> Die Nussschale (1234) wurde in Ozean (77,78) von Stürmen nach Ozean (78,78) abgetrieben. Sie erlitt dabei 2% Schaden. </text> <attribute name="ship"><shipref ref="ship_1234"/></attribute> <attribute name="from"><regionref ref="region_673256"/></attribute> <attribute name="to"><regionref ref="region_322167"/></attribute> <attribute name="damage"><int>2</int></attribute> </message> </message>	Messages können den Text in fertig gerenderter form enhalten. (Sprachabhängig) Attribute sollten nicht nur einfach Werte sondern auch Listen enthalten können. Ideal wäre die Attribute typisiert zu speichern, dann muss diese Info nicht aus dem Messagetyp geholt werden. Eine Verschachtelung von Messages sollte möglich sein
Messages (Alternative)
<message id="message_123456" type="msgtype_23423546"> <msgtext xml:lang="de"> Die <link name="ship" role="ship" ref="ship_1234">Nussschale (1234)</link> segelt von <link name="from" role="region" ref="region_653456">Irgendwo (1,2)</link> nach <regionref name="to" ref="region_653567">Nirgendwo (99,99)</regionref>. Dabei wurden <msgfunc name="through" type="regions"><regionref ref="region_953456">Ozean (1,3)</regionref>, <regionref ref="region_68656">Ozean (1,4)</regionref>, ... und <regionref ref="region_114562">Ozean (98,99)</regionref></msgfunc> durchquert. </msgtext> </message>	Messages enthalten hier Text und ihre Attribute gemischt. d.h. es ist immer klar aus welchem Teil der Pattern welcher Text erzeugt wurde. Mithilfe der Pattern lässt er sich auch bei fehlenden Referenzen halbwegs in andere Sprachen übersetzen, da man dann auch den Inhalt der anderen Sprache zurückgreifen kann. Dann steht zwar in der englischen Meldung auch Ozean (1,3) statt ocean (1,3) aber besser so als komplett deutsch ausgeben zu müssen, weil nicht renderbar wegen fehlender Referenzen.
Regionen
<region id="region_126788"> <coordinate x="14" y="27"/> <name>xxxxx</name> <descr>dsfsf sdf sdf</descr> <type role="terrain" ref="terrain_plain"/>	Regionen, hier versehen mit einer Koordinate. Wie wir verschiedene Ebenen Kennzeichen müssen wir noch diskutieren. Eine Z-Koordinate ist denkbar. Ein Element <maplevel> wäre aber auch nicht schlecht. Für subregionen will man ggf. keinen Terraintyp - deshalb sollte das type Attribut von region optional sein.
Regionsresourcen
<resources> <resource type="resourcetype.mallorntrees">50</resource> <resource type="resourcetype.mallornsaplings">10</resource> <resource type="resourcetype.laen"> <level depth="33">10</level> <level depth="34">12</level> </resource> <resource type="resourcetype.silver">10000</resource> <resource type="resourcetype.peasant">1000</resource> <resource type="resourcetype.elvendear" quantity="many"/> <resource type="resourcetype.elvendear">many</resource> </resource> </resources>	Mal ne dumme Frage am Anfang: Kann man Resourcen nicht vielleicht einfach als Gegenstände der Region auffassen? Vermutlich nicht weil es noch viele Besonderheiten gibt. Im objektorientieren vielleicht schon da könnte man Resourcen als Sonderform von Items definieren. type referenziert auf den entsprechenden resourcetype. Wenn der nicht in den Regeln vorhanden ist, sollte der Client natürlich trotzdem den Eintrag verarbeiten, er hat nur keine Infos über den Typ. Menge im Element codieren, oder als Attribut? Da es sich um die wichtigste info zur Resource handelt, ist es denke ich sinnvoll das im Element abzulegen. Stufenabhängigkeit als Attribut oder als Subelement? Hab es mal als Subelement eingebaut, mit mehreren angezeigten Schichten. Weitere Zusätzliche Attribute je nach Resourcentyp? Denke nicht, zumindest nicht solange sich solche werte ausrechnen lassen.
Handel
<trade> <offer amount="10"> <item role="trade_give" ref="itemtype_silver" amount="5"/> <item role="trade_get" ref="itemtype_balm" amount="1"/> </offer> <offer amount="1"> <item role="trade_give" ref="itemtype_juwel" amount="2500"/> <item role="trade_give" ref="itemtype_wood" amount="200"/> <ship role="trade_get" ref="shiptype_caravel" amount="1"/> </offer> <offer> <item role="trade_give" ref="itemtype_wood" amount="25"/> <ship role="trade_get" ref="ship_1234234324" turns="10"/> </offer> <offer> <link role="trade_start" ref="region_3431245324"> <item role="trade_get" ref="itemtype_wood" amount="25"/> </link> <link role="trade_end" ref="region_132876878798" turns="10"> <item role="trade_give" ref="itemtype_wood" amount="25"/> <item role="trade_get" ref="itemtype_silver" amount="2000"/> </link> </offer> </trade>	Wir erlauben Handel prinzipiell bei jedem Spielobjekt, d.h. global, Region, Einheit, Schiff, Gebäude, ... Gehandelt werden können Items oder Spielobjekte oder Typen von Spielobjekten Ein Verleih kann über eine zeitliche Begrenzung erreicht werden Eine Dienstleistung wie Waren von A nach B ist ggf. auch möglich
Einheiten
<unit id="unit_mag3" key="mag3"> <name ...> <text rel="public" xml:lang="de">Er schützt die Region.</text> <text rel="public" xml:lang="en">He protects the region.</text> <text rel="private">Botschafter (1234) ist ein parteigetarnter Spion der xxx</text> <race rel="true" ref="race_daemons"/> <race rel="stealth" ref="race_halfling"/> <race ref="race_halfling"/> <size>1</size> <faction ref="faction_awsm"/> <faction rel="true" ref="faction_Lotr"/> <faction rel="stealth" ref="faction_awsm"/> <group ref="grp_12"/> <prefix ref="prfx_dark"/> <link rel="familiar_of" ref="unit_mag1"/> <link rel="siege" ref="bldg_1234"/> <guard/> <status rel="combat" value="aggressive"/> <status rel="aid" value="false"/> <status rel="hunger" value="true"/> <status rel="stealth" value="14"/> <spells type="magic_gwyrrd"> <spell type="spell_xxx"/> <spell type="spell_xxy"/> </spells> <items> <item type="item_laen">14</item> <item type="item_wood">44</item> </items> <skills> <skill name="skill_perception" value="17"/> <skill type="skill_camouflage" value="4"/> </skills> <effect> <keytext key="ew34" xml:lang="de"> Die Einheit fühlt sich sehr stark. </keytext> </effect> <effect> <item type="item_sevenmilestea" amount="7"/> </effect> <message ...> </unit> Partei-Information ist Betrachter-abhaenging, muss qualifiziert sein. Mehr als eine Partei-Info pro Einheit ist moeglich. Rassen-Information ist Betrachter-abhaenging, muss qualifiziert sein. Mehr als eine Partei-Info pro Einheit ist moeglich. Bei camouflage bin ich mir auch unsicher. Wichtig ist, Man kann sich sinnigerweise nur als eine Rasse, eine Partei oder mit einer bestimmten Stufe tarnen. Ebenso unklar ist, wie man den ganzen Magiebereich flexibel abbildet. Magier haben bei Eressea ein Magiegebiet, bei anderen Spielen ggf. mehrere. Sprüche gehören zu einem Magiegebiet. Vertraute bei Eressea haben eventuell Sprüche, ohne diese aber einem Magiegebiet zuzuordnen. Bei Eressea gibt es Aura und Maximale Aura (prinzipiell ~ permanente Aura). Das kann man als Gegenstände auffassen, diese lassen sich aber in ihrer Menge nicht wie üblich übergeben. Trefferpunkte sind auch in diesem Bereich anzusiedeln. Sie werden aber nur durch einen Gesundheitsstatus grob ausgedrückt. Also modellieren wir das alles einzeln oder lassen wir uns was allgemeines einfallen? Thoralf hat recht, ein wenig mehr Struktur als notwendig hilft die übersicht zu wahren. Deshalb stecken wir Talente, Gegenstände usw. lieber in ein container-element. Bei Elementen die oft gar nicht oder nur sehr selten in mehrzahl auftreten, würde ich darauf aber verzichten (z.b. Effekte)
Gebäude
<building id="building_h0us" key="h0us"> <type ref="bt_academy"/> <type rel="true" ref="bt_illusioncastle"/> <type rel="illusion" ref="bt_academy"/> <name>xxxxx</name> <descr>dsfsf sdf sdf</descr> <size>25</size>	Name und Beschreibung sind klar #PCDATA. Typ ist abhaengig vom Betrachter, die Qualitaet der Information muss also qualifiziert werden können.
Schiffe
<ship id="ship_ttnc" key="ttnc" type="boat"/> <name>... <descr>... <status tag="load">2000</status> <status tag="damage">2</status>	Schiffstyp als Attribut vom element ship, wegen referenzieren auf Regeln Beladung, Schaden, Baustatus, usw. sind m.E. nur simple "Statusinfos" für die es nicht jeweils ein extra Element braucht. Wie sich sowas auf freie Kapazität, Reichweite usw. auswirkt ist eh spielabhängig. Ausserdem heissen diese Attribute überall ein bisschen anders.
</region>
Messagetypen
<messagetype id="msgtype_5673456873"> <section>travel</section> <pattern locale="de"> <attribute name="unit"/> segelt von <attribute name="from"/> nach <attribute name="to"/>. Dabei wurden <function type="regions"><attribute name="through"></function> durchquert. </pattern> </messagetype>	So richtig gefällt mir das hier noch nicht. Man sollte anhand der Pattern bereits den Typ des jeweiligen Attributs erkennen. Vermutlich müsste jede $xyz() die es derzeit gibt, als extra Elementtyp in der (Eressea)-DTD definiert werden.
</atlantis>

Regelset

Mir stellt sich die Frage, ob das Regelset nur die "technischen" Infos enthalten soll, oder ob auch die UI-Infos hier direkt rein sollen. Damit meine ich die Lokalisierung und Icons. Solche Sachen könnten auch in einer zusätzlichen XML Datei definiert sein, die dann z.B. nur Übersetzungen enthält.

Die Icons sollen sowieso nach Möglichkeit nicht direkt referenziert sein, sondern in einer Grafikset-XML verwaltet werden. D.h. es wird nur auf die im Grafikset eindeutigen IDs referenziert. Natürlich kann man auch das Grafikset spielabhängig gestalten und dort die Bindung der Icons an die Spielobjekte vornehmen.

Gleiches gilt für die Übersetzungen von Namen. Die können ebenso als "Benennungsset" spielabhängig und in einer Extra Datei gehalten werden und auf Spielobjekte referenzieren.

Und noch ein Dokument fuer eine Spiel-Definition

<!DOCTYPE atlantis PUBLIC "-//PBEM//DTD Atlantis 1.0//EN" "http://eressea.de/atlantis-ruleset.dtd">
<?xml version="1.0" encoding="UTF-8"?>
<atlantis>
  <itemcategory id="itemcategory_resource">
    <name lang="de">Ressource</name>
    <useicon ref="icon_resource">
  </itemcategory>

  <itemtype id="itemtype_laen">
    <name lang="de">Laen</name>
    <weight>2</weight>
    <produce>
      <skill type="skilltype.bergbau" minlevel="7" productionpoints="7"/>
      <building type="buildingtype.mine" required="yes"/>
      <components>
        <resource type="resourcetype.laen">1</resource>
      </components>
    </produce>
    <useicon ref="icon_laen"/>
    <category ref="itemcategory_resource"/>
  </itemtype>
  <itemtype id="peasantblood">
    <produce>
      <skill type="skilltype.alchemy" minlevel="4" productionpoints="4"/>
      <components>
        <resource type="resourcetype.peasant">1</resource>
        <item type="fjordfungus">1</item>
        ...
      </components>
      <command><cmd_make/> <amount optional="true"/> ...</command>
    </produce>
  </itemtype>

  <race/>
  <plane/>
  <terraintype/>
  <skilltype/>
  <buildingtype id="buildingtype_mine">
    ...
    <useicon ref="icon_mine">
      <placement role="map" x="0%" y="30%"/>
    </useicon>
  </buildingtype>
  <shiptype/>
  <command/>
 
</atlantis>

Elemente im Detail

Um mal einen Ansatzpunkt für die DTD zu bekommen und auch als Doku werden hier die Elemente mit ihren Eigenschaften gelistet. Beispiel sollen sich auf das nötigste beschränken, also auch nicht mehr als 10 Zeilen beanspruchen.

<gameobject/>

• Attribute:
  • id = Dokumentweit eindeutiger Schlüssel
  • type = Basistyp des Spielobjektes (Flotte, Insel, Kolonie, Karawane, ...)
  • key = innerhalb des Typs des Spielobjektes eindeutiger Schlüssel
• Subelemente:
  • Beschreibende: <name/>? <descr/>? <plaintext/>*
  • Ausprägung (Rasse, Held(entyp)): <type/>*
  • Daten/Status: [[#|]]* <status/>*
  • Verweise auf andere Spielobjekte: <link/>*
  • Gegenstände/Besitz: <items/>?
  • Hierarchiebildung: <gameobject/>* <faction/>* <region/>* <unit/>* <ship/>* <building/>*

Beispiel:

<gameobject id="fleet_471b" type="fleet" key="471b">
  <link role="master" ref="ship_45t6"/>
  <link role="slave" ref="ship_t426"/>
  <link role="slave" ref="ship_vfr7"/>
</gameobject>

<world/>

• Subelemente: wie <gameobject/>

<faction/>

• Attribute: id und key
• Subelemente: wie <gameobject/>

<region/>

• Attribute: id und key
• Subelemente: wie <gameobject/>

<unit/>

• Attribute: id und key
• Subelemente: wie <gameobject/> zusätzlich:
  • Erfahrung/Talente: <skills/>?
  • Befehle: <commands/>?

<ship/>

• Attribute: id und key
• Subelemente: wie <gameobject/>

<building/>

• Attribute: id und key
• Subelemente: wie <gameobject/>

<name/>

• Attribute:
  • lang = Die Sprache des Elementinhalts. Default ist die Sprache des Reports oder der Konfigurationsdatei. (optional)
  • stemming = (singular|plural) gibt an, wie dieses Element in bestimmten Beugungen heisst. Default ist singular. (optional)
• Subelemente:
• #PCDATA

<descr/>

• Attribute:
  • lang = Die Sprache des Elementinhalts. Default ist die Sprache des Reports oder der Konfigurationsdatei. (optional)
• Subelemente:
• #PCDATA

<link/>

• Attribute:
  • role = Die Rolle oder Beziehung des Verweises
  • ref = Das referenzierte Element, der Typ kann dann über das Element ermittelt werden.
• Subelemente:
• ?

Siehe auch

• CR Format

External Links

• Accelerating XPath Location Steps
• CRXML Format und Tools