LocoXML

XML

Nun was erhalten wir denn, wenn wir mit 'nem großen Hammer ... ähh, Pardon LocoTool auf ein unschuldiges Locomotion-Objekt einschlagen?
RICHTIG: Je nach LocoTool-Parametern entweder eine ganz große oder viele kleine Grafikdateien im PNG-Format und eine XML-Datei. Mit Letzterer wollen wir uns zuerst beschäftigen. Dazu machen wir gleich mal eine kleine Exkursion nach XML.

Gleich vorweg: Dies ist keine Abhandlung über XML an sich, sondern nur eine Zusammenfassung der speziellen Dinge, die zum Verständnis der Locomotion XML-Dateien nötig sind. Der geneigte Leser, der tiefer in die Materie XML einzudringen wünscht, sei auf entsprechende Fachliteratur oder das Internet verwiesen.

Hier nun die Begriffsdefinitionen, die in diesem Tutorial Verwendung finden:

Alle XML-Elemente bestehen aus so genannten Tags. Dabei handelt es sich nicht etwa um Kalendertage, sondern der Begriff kommt aus dem Englischen und heißt soviel wie Marke oder Etikett.
Tags sind in spitze Klammern eingeschlossen <Tag>.
Ein XML-Element in Locomotion besteht aus einem Start- und einem Ende-Tag. Beide haben den gleichen Namen wobei dem Ende-Tag ein Schrägstrich vorangestellt wird.

Das sieht schon mal so aus:

<unknown></unknown>

Ein Tag kann Attribute enthalten, die hier rot dargestellt sind.
Ein Attribut besteht aus einem Namen, gefolgt von einem Gleichheitszeichen und seinem Inhalt, der in Gänsefüßchen eingeschlossen ist.
Ein Attributname innerhalb eines Tags muss eindeutig sein. Er darf in einem Tag nicht mehrmals vorkommen.

<unknown name="field_BE[4]" size="1"></unknown>

<!-- So etwas geht nicht! -->
<unknown size="1" size="5"></unknown>

Ein Element kann einen Inhalt besitzen, der entweder aus Werten ...

<unknown>65535</unknown>

<thelord>Chris Sawyer</thelord>

... oder auch aus weiteren Elementen besteht. (Verschachtelung)

<bitmask name="flags" size="4">
	<bit name="needall">0</bit>
	<bit name="canincreaseproduction">0</bit>
	<bit name="candecreaseproduction">0</bit>
</bitmask>

Kommentare sollen manchmal den Quelltext erläutern und sind hier grün dargestellt. In Locomotion XML-Dateien werdet ihr sie nie finden.

<!-- Ich bin ein Kommentar -->

Wenn ihr jemals eigene XMLs strickt, lasst die Kommentare besser weg. Ich weiß nicht, ob LocoTool sie ohne weiteres schluckt. Ich hab's auch noch nicht ausprobiert.

Back to Locomotion

Kommen wir nun von XML im Allgemeinen zu Locomotion im Besonderen. Hier gelten noch ein paar Regeln:

Tag- und Attributnamen werden von LocoTool vorgegeben sie dürfen nie verändert werden. Sie beschreiben die Struktur von Locomotion-Objekten.
Attributinhalte sind ebenfalls vorgegeben, dürfen aber manchmal verändert werden.
Die Elementinhalte selbst können meistens verändert werden. (Wo es denn sinnvoll erscheint.)

Schauen wir uns aber zuerst einmal das grundlegende Gerüst einer Locomotion-XML Datei an:

<?xml version="1.0" encoding="ISO-8859-1"?>
<!-- Headerzeile. Bei allen Loco-XMLs gleich -->
<object class="0x9C" subclass="0x11827C" name="BLDALP1 "><chunk compression="1">
<!-- Und hier wird's zum ersten Mal wichtig. -->
	...
	...
	<!-- Hier steht alles drin, was unsere Objekte so schön macht. -->
	...
	...
<!-- Zum Ende wird alles noch sauber abgeschlossen. -->
</chunk></object>

Die Headerzeile ist immer da und bleibt so. PUNKT.

Aber schon haben wir die erste interessante Konstruktion vor uns, das Objekt selbst. Formatieren wir es zur Veranschaulichung etwas um und wir erkennen gleich die erste Verschachtelung.

<object ... >
	<chunk compression="1">

	...

	</chunk>
</object>

Das innere Element chunk, das den Rest umschließt, beschreibt die Kompressionsmethode für LocoTool. Es ist ebenfalls so zu belassen, wie es ist.

Das äußere Element object besitzt aber schon ein paar interessante Attribute auf die wir sofort näher eingehen wollen.

<object class="0x9C" subclass="0x11827C" name="BLDALP1 ">

class
Hier drin versteckt sich die Objektklasse. Locomotion kennt 34 davon (0-33). Dabei handelt es sich um die verschiedenen Objekttypen (Häuser, Fahrzeuge, Schiffe ...). Versteckt deshalb, weil der Wert hexadezimal kodiert ist und man das höchste Bit löschen muss ('0x80' abziehen). Für Gebäude wäre das z.B. '0x9C' - '0x80' = '0x1C'. Das sind dezimal 28. Diese Klassennummer kommt immer dann zum Tragen, wenn sich Objekte auf andere Objektypen beziehen. Dazu an anderer Stelle mehr.
Bei Fahrzeugen, die mit dem VehicleCreator gebaut werden, wird dieser Wert automatisch gesetzt. Da die meisten Modder ihre neuen Objekte eh aus bereits bestehenden Vorlagen herleiten, macht eine Änderung dieses Wertes wenig Sinn.
Nun ja. Ich hab mal von jemandem gehört, der die Gebäudeklasse in die Fahrzeugklasse geändert haben soll, und dann Kirchen auf Schienen laufen ließ oder so. Sah echt lustig aus.
subclass
Dies ist ein Loreley Wert. 'Ich weiß nicht, was soll es bedeuten ...'. Im Internet kursieren zwar ab und zu Gerüchte über ihn, aber so richtig schlau geworden bin ich darüber auch noch nicht.
name
Und hier der Star der Zeile: Die allseits geschätzte und berühmte ObjID. Ihr erinnert euch? Sie muss eindeutig sein für jedes installierte Locomotion Objekt. Bildungsregel: 8 Standard-ASCII Zeichen oder Ziffern, nur Großbuchstaben, keine nationalen Sonderzeichen. Bei Bedarf aufzufüllen mit Leerzeichen. Aber, was erzähl ich euch da noch.

Wiederkehrende Strukturen

Da wir schon die äußere Hülle einer LocoXML-Datei weg gepuhlt haben, beschäftigen wir uns doch mal mit den weiteren Innereien. Die meisten Elemente (einfache Variablen) haben folgendes Format:

<variable name="numaux2ent" size="1">1</variable>
<variable name="earliestyr" size="2">1910</variable>

Sie haben einen Namen name und eine Größe size. Bei Zahlenwerten beschreibt die Größe die Anzahl von Bytes die dieser Wert belegt. Bei Zeichenketten verhält es sich ein wenig anders. Sie haben kein size Attribut. Die Größe ergibt sich aus der Anzahl der verwendeten Zeichen selbst.

<description num="0" language="0">Building</description>

Dann gibt es ja noch Bitwerte, die nur die Zustände 0 bzw. 1 belegen können. Hier wäre eine Größenangabe sinnlos. Allerdings sind sie immer in Feldern organisiert, die sehr wohl eine definierbare Größe besitzen.

<!-- Dieses Bitfeld belegt 4 Byte also 32 Bit -->
<bitmask name="flags" size="4">
	<!-- Hier folgen einzelne Bits -->
	<bit name="bit_2">1</bit>
	<bit name="bit_6">1</bit>
	<bit name="bit_9">1</bit>
	<bit name="bit_10">1</bit>
	<bit name="needall">0</bit>
	<bit name="canincreaseproduction">0</bit>
	<bit name="candecreaseproduction">0</bit>
	<bit name="bit_19">1</bit>
</bitmask>

Nun würde man erwarten, daß in diesem Beispiel bei 4 Byte Größe 32 Bitwerte untereinander stehen müssten. Jedoch gibt LocoTool unbekannte oder nicht verwendete Bits nicht aus.

Bekanntlich gibt es aber auch Felder (Arrays), die Zahlen oder andere Werte enthalten. Diese haben folgende Struktur:

<!-- Diese Zeile beschreibt das Datenfeld -->
<auxdata name="aux_5" size="1" num="8" type="0">
	<!-- Hier folgen die einzelnen Einträge -->
	<unknown name="field_0[2]" size="1">1</unknown>
	<unknown name="field_0[3]" size="1">1</unknown>
	<unknown name="field_0[5]" size="1">1</unknown>
	<unknown name="field_0[6]" size="1">1</unknown>
	<unknown name="field_0[7]" size="1">1</unknown>
</auxdata>

Die Feldbeschreibung enthält den Feldnamen name, die Größe eines einzelnen Feldelementes size und die Anzahl aller Feldelemente num. Über die Bedeutung des Attributes type bin ich mir noch nicht so richtig im Klaren. Wer also Infos dazu hat, möge mich bitte anmailen.

Ein Feldelement besitzt einen Namen, in dem seine Position eingebettet ist, nochmal die Größenangabe und natürlich einen Inhaltswert. Bitte beachten: Die Nummerierung der Feldelemente beginnt bei 0. Das heißt, das letzte Element hat die Nummer Anzahl - 1.
Nun scheinen aber in diesem Beispiel einige Feldelemente zu fehlen. Keine Panik! Sie existieren dennoch. Allerdings sind ihre Werte 0. Und wenn man LocoTool ohne den Parameter -u startet, lässt es diese beim Dekodieren aus.

Damit hätten wir schon fast alles über die LocoXML-Datenstrukturen abgeklärt. Besonderheiten, die sich bei einzelnen Objekten ergeben, werde ich dann dort näher erläutern.

Fehlt eigentlich nur noch die Struktur für die Spritegrafiken. Aufgrund des Umfangs hab ich diesen ein eigenes Kapitel gewidmet.

	Einleitung	LocoXML	Sprites	Farben	Bauwerke	Bahnkram	Fahrzeuge	Krimskrams
XML XML Nun was erhalten wir denn, wenn wir mit 'nem großen Hammer ... ähh, Pardon LocoTool auf ein unschuldiges Locomotion-Objekt einschlagen? RICHTIG: Je nach LocoTool-Parametern entweder eine ganz große oder viele kleine Grafikdateien im PNG-Format und eine XML-Datei. Mit Letzterer wollen wir uns zuerst beschäftigen. Dazu machen wir gleich mal eine kleine Exkursion nach XML. Gleich vorweg: Dies ist keine Abhandlung über XML an sich, sondern nur eine Zusammenfassung der speziellen Dinge, die zum Verständnis der Locomotion XML-Dateien nötig sind. Der geneigte Leser, der tiefer in die Materie XML einzudringen wünscht, sei auf entsprechende Fachliteratur oder das Internet verwiesen. Hier nun die Begriffsdefinitionen, die in diesem Tutorial Verwendung finden: Alle XML-Elemente bestehen aus so genannten Tags. Dabei handelt es sich nicht etwa um Kalendertage, sondern der Begriff kommt aus dem Englischen und heißt soviel wie Marke oder Etikett. Tags sind in spitze Klammern eingeschlossen <Tag>. Ein XML-Element in Locomotion besteht aus einem Start- und einem Ende-Tag. Beide haben den gleichen Namen wobei dem Ende-Tag ein Schrägstrich vorangestellt wird. Das sieht schon mal so aus: <unknown></unknown> Ein Tag kann Attribute enthalten, die hier rot dargestellt sind. Ein Attribut besteht aus einem Namen, gefolgt von einem Gleichheitszeichen und seinem Inhalt, der in Gänsefüßchen eingeschlossen ist. Ein Attributname innerhalb eines Tags muss eindeutig sein. Er darf in einem Tag nicht mehrmals vorkommen. <unknown name="field_BE[4]" size="1"></unknown> <!-- So etwas geht nicht! --> <unknown size="1" size="5"></unknown> Ein Element kann einen Inhalt besitzen, der entweder aus Werten ... <unknown>65535</unknown> <thelord>Chris Sawyer</thelord> ... oder auch aus weiteren Elementen besteht. (Verschachtelung) <bitmask name="flags" size="4"> <bit name="needall">0</bit> <bit name="canincreaseproduction">0</bit> <bit name="candecreaseproduction">0</bit> </bitmask> Kommentare sollen manchmal den Quelltext erläutern und sind hier grün dargestellt. In Locomotion XML-Dateien werdet ihr sie nie finden. <!-- Ich bin ein Kommentar --> Wenn ihr jemals eigene XMLs strickt, lasst die Kommentare besser weg. Ich weiß nicht, ob LocoTool sie ohne weiteres schluckt. Ich hab's auch noch nicht ausprobiert. Back to Locomotion Back to Locomotion Kommen wir nun von XML im Allgemeinen zu Locomotion im Besonderen. Hier gelten noch ein paar Regeln: Tag- und Attributnamen werden von LocoTool vorgegeben sie dürfen nie verändert werden. Sie beschreiben die Struktur von Locomotion-Objekten. Attributinhalte sind ebenfalls vorgegeben, dürfen aber manchmal verändert werden. Die Elementinhalte selbst können meistens verändert werden. (Wo es denn sinnvoll erscheint.) Schauen wir uns aber zuerst einmal das grundlegende Gerüst einer Locomotion-XML Datei an: <?xml version="1.0" encoding="ISO-8859-1"?> <!-- Headerzeile. Bei allen Loco-XMLs gleich --> <object class="0x9C" subclass="0x11827C" name="BLDALP1 "><chunk compression="1"> <!-- Und hier wird's zum ersten Mal wichtig. --> ... ... <!-- Hier steht alles drin, was unsere Objekte so schön macht. --> ... ... <!-- Zum Ende wird alles noch sauber abgeschlossen. --> </chunk></object> Die Headerzeile ist immer da und bleibt so. PUNKT. Aber schon haben wir die erste interessante Konstruktion vor uns, das Objekt selbst. Formatieren wir es zur Veranschaulichung etwas um und wir erkennen gleich die erste Verschachtelung. <object ... > <chunk compression="1"> ... </chunk> </object> Das innere Element chunk, das den Rest umschließt, beschreibt die Kompressionsmethode für LocoTool. Es ist ebenfalls so zu belassen, wie es ist. Das äußere Element object besitzt aber schon ein paar interessante Attribute auf die wir sofort näher eingehen wollen. <object class="0x9C" subclass="0x11827C" name="BLDALP1 "> class Hier drin versteckt sich die Objektklasse. Locomotion kennt 34 davon (0-33). Dabei handelt es sich um die verschiedenen Objekttypen (Häuser, Fahrzeuge, Schiffe ...). Versteckt deshalb, weil der Wert hexadezimal kodiert ist und man das höchste Bit löschen muss ('0x80' abziehen). Für Gebäude wäre das z.B. '0x9C' - '0x80' = '0x1C'. Das sind dezimal 28. Diese Klassennummer kommt immer dann zum Tragen, wenn sich Objekte auf andere Objektypen beziehen. Dazu an anderer Stelle mehr. Bei Fahrzeugen, die mit dem VehicleCreator gebaut werden, wird dieser Wert automatisch gesetzt. Da die meisten Modder ihre neuen Objekte eh aus bereits bestehenden Vorlagen herleiten, macht eine Änderung dieses Wertes wenig Sinn. Nun ja. Ich hab mal von jemandem gehört, der die Gebäudeklasse in die Fahrzeugklasse geändert haben soll, und dann Kirchen auf Schienen laufen ließ oder so. Sah echt lustig aus. subclass Dies ist ein Loreley Wert. 'Ich weiß nicht, was soll es bedeuten ...'. Im Internet kursieren zwar ab und zu Gerüchte über ihn, aber so richtig schlau geworden bin ich darüber auch noch nicht. name Und hier der Star der Zeile: Die allseits geschätzte und berühmte ObjID. Ihr erinnert euch? Sie muss eindeutig sein für jedes installierte Locomotion Objekt. Bildungsregel: 8 Standard-ASCII Zeichen oder Ziffern, nur Großbuchstaben, keine nationalen Sonderzeichen. Bei Bedarf aufzufüllen mit Leerzeichen. Aber, was erzähl ich euch da noch. Wiederkehrende Strukturen Wiederkehrende Strukturen Da wir schon die äußere Hülle einer LocoXML-Datei weg gepuhlt haben, beschäftigen wir uns doch mal mit den weiteren Innereien. Die meisten Elemente (einfache Variablen) haben folgendes Format: <variable name="numaux2ent" size="1">1</variable> <variable name="earliestyr" size="2">1910</variable> Sie haben einen Namen name und eine Größe size. Bei Zahlenwerten beschreibt die Größe die Anzahl von Bytes die dieser Wert belegt. Bei Zeichenketten verhält es sich ein wenig anders. Sie haben kein size Attribut. Die Größe ergibt sich aus der Anzahl der verwendeten Zeichen selbst. <description num="0" language="0">Building</description> Dann gibt es ja noch Bitwerte, die nur die Zustände 0 bzw. 1 belegen können. Hier wäre eine Größenangabe sinnlos. Allerdings sind sie immer in Feldern organisiert, die sehr wohl eine definierbare Größe besitzen. <!-- Dieses Bitfeld belegt 4 Byte also 32 Bit --> <bitmask name="flags" size="4"> <!-- Hier folgen einzelne Bits --> <bit name="bit_2">1</bit> <bit name="bit_6">1</bit> <bit name="bit_9">1</bit> <bit name="bit_10">1</bit> <bit name="needall">0</bit> <bit name="canincreaseproduction">0</bit> <bit name="candecreaseproduction">0</bit> <bit name="bit_19">1</bit> </bitmask> Nun würde man erwarten, daß in diesem Beispiel bei 4 Byte Größe 32 Bitwerte untereinander stehen müssten. Jedoch gibt LocoTool unbekannte oder nicht verwendete Bits nicht aus. Bekanntlich gibt es aber auch Felder (Arrays), die Zahlen oder andere Werte enthalten. Diese haben folgende Struktur: <!-- Diese Zeile beschreibt das Datenfeld --> <auxdata name="aux_5" size="1" num="8" type="0"> <!-- Hier folgen die einzelnen Einträge --> <unknown name="field_0[2]" size="1">1</unknown> <unknown name="field_0[3]" size="1">1</unknown> <unknown name="field_0[5]" size="1">1</unknown> <unknown name="field_0[6]" size="1">1</unknown> <unknown name="field_0[7]" size="1">1</unknown> </auxdata> Die Feldbeschreibung enthält den Feldnamen name, die Größe eines einzelnen Feldelementes size und die Anzahl aller Feldelemente num. Über die Bedeutung des Attributes type bin ich mir noch nicht so richtig im Klaren. Wer also Infos dazu hat, möge mich bitte anmailen. Ein Feldelement besitzt einen Namen, in dem seine Position eingebettet ist, nochmal die Größenangabe und natürlich einen Inhaltswert. Bitte beachten: Die Nummerierung der Feldelemente beginnt bei 0. Das heißt, das letzte Element hat die Nummer Anzahl - 1. Nun scheinen aber in diesem Beispiel einige Feldelemente zu fehlen. Keine Panik! Sie existieren dennoch. Allerdings sind ihre Werte 0. Und wenn man LocoTool ohne den Parameter -u startet, lässt es diese beim Dekodieren aus. Damit hätten wir schon fast alles über die LocoXML-Datenstrukturen abgeklärt. Besonderheiten, die sich bei einzelnen Objekten ergeben, werde ich dann dort näher erläutern. Fehlt eigentlich nur noch die Struktur für die Spritegrafiken. Aufgrund des Umfangs hab ich diesen ein eigenes Kapitel gewidmet.