Inhaltsverzeichnis
Für die Konfiguration einer tjger-Applikation sind bestimmte Werte in der Einstellungs-, der Menü- und der Meldungsdatei von HGBase notwendig. Für die spielbezogene Konfiguration gibt es eine zusätzliche XML-Datei.
Für eine detaillierte Beschreibung der Dateien siehe im Abschnitt Verwendung von HGBase das Kapitel XML-Dateien bearbeiten.
Die Datei für die Einstellungen wird um den Eintrag fileTjger, der festlegt, wo die Datei für die Spielkonfiguration zu finden ist und den Eintrag fileProfile, der festlegt, wo die Datei für die Spielerprofile zu finden ist, erweitert. Ist keine Profildatei eingetragen, so werden keine Profile gespeichert (die Anzahl der gespielten und gewonnenen Spiele und die Gesamtpunktezahl für die Spieler werden aber dennoch gemerkt, wenn dies so definiert ist).
<set name="fileTjger" value="/xml/tjger_eye.xml" />
<set name="fileProfile" value="tjger_eye.tpf" />
Musikdateien, welche im Programm abgespielt werden sollen, werden ebenfalls hier definiert. Der playAudio()-Methode der MainFrame-Klasse wird der in dieser Datei definierte Schlüssel übergeben:
<set name="soundCard" value="/sound/card.wav" />
<set name="soundDice" value="/sound/dice.wav" />
Das Menü von tjger (MainMenu) bietet zusätzliche Funktionalität zum HGBase-Menü an. Um diese zu verwenden, kann die Datei für das Menü um entsprechende Einträge erweitert werden.
Der Menüpunkt file.next erlaubt standardmäßig das Starten eines neuen Spiels auf Basis des aktuellen. Gibt es kein aktuelles Spiel, so wird der Dialog für neue Spiele angezeigt. Mit dem Befehl file.gameinfo wird der Dialog mit Spielinformationen (siehe Die Standard-Dialoge) angezeigt:
<item id="file.next" type="action" />
<item id="file.gameinfo" type="action" />
Wichtige Menüpunkte, die hinzugekommen sind, sind jene zum Zoomen. Die einzelnen Einträge des Zoom-Menüs befinden sich im Menü mit der Id zoom. Dieses Menü wird auch als PopUp-Menü in der Statusleiste angezeigt, falls dieses aktiviert wurde (siehe Erstellen einer Anwendung):
<menu id="zoom">
<item id="zoom.fitwidth" type="action" />
<item id="zoom.fitheight" type="action" />
<item id="zoom.fitoptimal" type="action" />
<item id="zoom.variable;zoom.75;zoom.100" option="zoom.menu" type="radio" />
<item id="zoom.zoomin" type="action" shortcut="Plus" />
<item id="zoom.zoomout" type="action" shortcut="Minus" />
<item/>
<item id="zoom.fitwindow" option="zoom.fitwindow" type="checkbox" />
</menu>
Zudem gibt es einen Standardmenüpunkt zum Zusammenstellen der Spielmaterialien (Hintergrund, Spielbretter, Karten, Deckblätter und Spielfiguren) und zum Einstellen des Netzwerk-Ports:
<item id="settings.parts" type="action" />
<item id="settings.network" type="action" />
und zum Anzeigen des tjger-Informationsdialogs:
<item id="help.tjger" type="action" />
Zudem gibt es Standardbefehle zum Anzeigen der Spielanleitung und der Spielhinweise (siehe dazu auch Die Standard-Dialoge):
<item id="help.instructions" type="action" shortcut="F1"/>
<item id="help.gamehints" type="action"/>
In der Einstellungsdatei kann man die Option hideNotShowAgainHintOption auf true setzen, damit keine Auswahlbox angezeigt wird, ob Hinweise automatisch angezeigt werden sollen.
Das Ein- und Ausschalten der Musik funktioniert, wie in Erstellen einer Anwendung erwähnt, über die Option nosound. Eine Möglichkeit ist es, diese Option im Menü zu verankern:
<item id="settings.nosound" option="nosound" type="checkbox" />
Eine weitere Standardoption ist das Einstellen, ob eine Speicherrückfrage gemacht werden soll:
<item id="settings.noconfirm" option="noconfirm" type="checkbox" />
Zum Ein- und Ausschalten des Aufnehmens eines Spielstandes (siehe Kapitel Spielstand debuggen), bietet sich der folgende Menüpunkt an:
<item id="settings.recordgame" option="recordgame" type="checkbox"/>10
Durch tjger kommen auch einige Standardmeldungen hinzu. Diese ergeben sich durch:
Die Standardmeldungen von HGBase und die Meldungen für die neuen Menüpunkte, die zusätzlichen Dialoge und die Fehlermeldungen sind genau definiert. Es wird empfohlen, die Datei mit den Standardmeldungen für tjger (/tjger/messages.xml) zu inkludieren. Beispiel für Deutsch, nicht vollständig:
<?xml version="1.0" encoding="ISO-8859-1"?>
<messages>
<include file="/hgb/lib/xml/messages.xml"/>
<language code="lan.de">
<msg code="-10705">Fehler beim Schreiben des Spielstands!</msg>
<msg code="-10706">Fehler beim Lesen des Spielstands!</msg>
<msg code="-30216">Konnte Verbindung zum Server nicht herstellen!</msg>
<msg code="-30218">Probleme beim Starten des Servers!</msg>
<msg code="-30301">Spieler konnten nicht intialisiert werden!</msg>
<msg code="-30303">Spiel konnte nicht gestartet werden!</msg>
<msg code="-30305">Fehler beim Übertragen des Spielstands!</msg>
<msg code="-30307">Fehler beim Übertragen des Spielzugs!</msg>
<msg code="error.sound">Fehler beim Abspielen der Musikdateien! %s</msg>
<msg code="err.onehuman">Es kann nur ein menschlicher Spieler mitspielen!</msg>
<msg code="err.nohuman">Es ist kein menschlicher Spieler ausgewählt.</msg>
<msg code="err.neednames">Alle Spieler benötigen einen Namen!</msg>
<msg code="err.samenames">Spielernamen dürfen nicht gleich sein!</msg>
<msg code="err.namewrong">Name hat ungültiges Zeichen '%s' !</msg>
<msg code="err.profileexists">Spielerprofil existiert bereits!</msg>
<msg code="err.nonetwork">Es sind keine Netzwerk-Spieler erlaubt!</msg>
<msg code="err.networkport">Geben Sie bitte einen gültigen Port ein!</msg>
<msg code="err.networknoip">Geben Sie bitte die Servers-Adresse ein!</msg>
<msg code="err.networkconhost">Es besteht keine Verbindung zum Server!</msg>
<msg code="err.networkconclients">Es sind noch nicht alle Spieler verbunden!</msg>
<msg code="err.networknoclients">Es ist kein Netzwerk-Spieler vorhanden!</msg>
<msg code="err.networksave">Netzwerk-Spiele können nicht gespeichert werden!</msg>
<msg code="err.networkclientnot">Diese Aktion ist nur für Server erlaubt!</msg>
<msg code="err.netabort">Die Verbindung wurde unterbrochen!</msg>
<msg code="err.netname">Der Spielername wird bereits verwendet!</msg>
<msg code="err.application">Auf dem Server läuft die Applikation '%s'!</msg>
<msg code="err.nextgame">Auf dem Server wurde ein neues Spiel gestartet!</msg>
<msg code="file">Spiel</msg>
<msg code="file.next">Noch ein Spiel</msg>
<msg code="file.gameinfo">Spielinformation...</msg>
<msg code="file.profiles">Profilverwaltung...</msg>
<msg code="view">Ansicht</msg>
<msg code="zoom">Maßstab</msg>
<msg code="zoom.fitwidth">An Breite anpassen</msg>
<msg code="zoom.fitheight">An Höhe anpassen</msg>
<msg <msg code="zoom.fitoptimal">Optimale Größe</msg>
<msg code="zoom.zoomin">Vergrößern</msg>
<msg code="zoom.zoomout">Verkleinern</msg>
<msg code="zoom.variable">Stufenlos...</msg>
<msg code="zoom.150">150%</msg>
<msg code="zoom.100">100%</msg>
<msg code="zoom.75">75%</msg>
<msg code="zoom.fitwindow">An Fenstergröße anpassen</msg>
<msg code="settings.recordgame">Neues Spiel aufnehmen</msg>
<msg code="settings.parts">Aussehen...</msg>
<msg code="settings.network">Netzwerk...</msg>
<msg code="settings.noconfirm">Keine Speichern-Rückfrage</msg>
<msg code="help.tjger">tjger...</msg>
<msg code="help.gamehints">Spielhinweise...</msg>
<msg code="help.instructions">Spielanleitung...</msg>
<msg code="dlg.filesave">Möchten Sie das Spiel speichern?</msg>
<msg code="dlg.fileclose">Möchten Sie das Spiel abbrechen?</msg>
<msg code="dlg.remove">Löschen</msg>
<msg code="dlg.newgame">Neues Spiel</msg>
<msg code="dlg.players">Spieler</msg>
<msg code="dlg.choosecolor">Farbe wählen</msg>
<msg code="dlg.chooseimage">Bild wählen</msg>
<msg code="dlg.asktosave">Einstellungen speichern?</msg>
<msg code="dlg.turnfinished">Durchgang beendet</msg>
<msg code="dlg.roundfinished">Runde beendet</msg>
<msg code="dlg.gamefinished">Spiel beendet</msg>
<msg code="dlg.currentgame">Aktuelles Spiel</msg>
<msg code="dlg.gamestatistics">Spielstatistik</msg>
<msg code="dlg.highscore">Bestenliste</msg>
<msg code="dlg.score">Punkte</msg>
<msg code="dlg.removescore">Punkte löschen</msg>
<msg code="dlg.removestatistics">Statistik löschen</msg>
<msg code="dlg.profileexists">Spielerprofil existiert bereits</msg>
<msg code="dlg.askprofileoverwrite">Es existiert bereits das Profil "%s"...</msg>
<msg code="dlg.warnprofileoverwrite">Es existieren bereits ...</msg>
<msg code="dlg.loadgame">Spiel laden</msg>
<msg code="dlg.overwrite">Überschreiben</msg>
<msg code="dlg.use">Verwenden</msg>
<msg code="dlg.all">Alle</msg>
<msg code="dlg.network">Netzwerk</msg>
<msg code="dlg.networkport">Server Port:</msg>
<msg code="dlg.networkreset">Zurücksetzen</msg>
<msg code="dlg.connect">Verbinden</msg>
<msg code="dlg.stop">Stoppen</msg>
<msg code="dlg.notshowagain">Hinweise nicht mehr automatisch anzeigen</msg>
<msg code="dlg.debugnextmovetitle">Spielzug abspielen</msg>
<msg code="dlg.askdebugnextmove">Wollen Sie den nächsten Spielzug abspielen?</msg>
<msg code="dlg.debugplayer">Spieler: </msg>
<msg code="dlg.debugmove">Spielzug: </msg>
<msg code="dlg.debuginvalidmove">Ungültiger Spielzug!</msg>
<msg code="type.human">Mensch</msg>
<msg code="type.computer">Computer</msg>
<msg code="type.network">Netzwerk</msg>
<msg code="network.none">Kein Netzwerkspiel</msg>
<msg code="network.server">Netzwerk-Server starten</msg>
<msg code="network.client">Mit Netzwerk-Server verbinden</msg>
<msg code="network.waitplayers">Warte auf andere(n) Spieler.</msg>
<msg code="gameinfo.numplayers">Anzahl der Spieler:</msg>
<msg code="status.roundfinished">Runde beendet</msg>
<msg code="status.gamefinished">Spiel beendet</msg>
<msg code="tooltip.scoreturn">Punkte des aktuellen Durchgangs</msg>
<msg code="tooltip.scoreround">Punkte der aktuellen Runde</msg>
<msg code="tooltip.scoregame">Gesamtpunkte</msg>
<msg code="tooltip.gamesplayed">Anzahl gespielter Spiele</msg>
<msg code="tooltip.gameswon">Anzahl gewonnener Spiele</msg>
<msg code="game.cardset">Kartenset</msg>
<msg code="game.cover">Deckblatt</msg>
<msg code="game.pieceset">Spielsteine</msg>
<msg code="game.board">Spielbrett</msg>
<msg code="game.background">Hintergrund</msg>
<msg code="game.arrangement">Zusammenstellung</msg>
</language>
...
</messages>
Die Meldungen für die Spielelemente ergeben sich auf Grund der Einträge in der Datei für die Spielkonfiguration. Die Meldungen, die mit game. beginnen stehen für die Standardspielmaterialien.
Auch die Konfigurationsdatei von HGBase speichert bei einer tjger-Applikation automatisch mehr Werte. Diese zusätzlichen Konfigurationen sind entweder durch Menüeinstellungen (siehe oben) oder durch das Abspeichern von bestimmten Spieleinstellungen des Benutzers (wie z.B. Spielernamen oder Zusammenstellung des Spielfelds) vorhanden. Die Namen dieser Spieleinstellungen sind in der Klasse tjger.lib.ConstantValue festgelegt, siehe dazu auch Bibliotheksfunktionen .
Die Datei für die Spielkonfiguration (z.B. tjger.xml) hat als Wurzelelement den Knoten tjger und besteht aus mehreren Bereichen. Eine vollständige Beispieldatei ist im Abschnitt Beispielanwendung 'Eye of the Tjger' zu finden. Zuerst wird ein Bereich mit generellen Einstellungen definiert, dann gibt es einen Bereich für die Spielerdefinitionen und anschließend Bereiche für die einzelnen Spielmaterialien.
Die Einstellungen werden von der Klasse tjger.game.completed.GameConfig eingelesen und können auch über diese Klasse abgefragt werden. Für diverse Angaben zu den Spielern ist zudem die Klasse tjger.game.completed.PlayerManager zuständig.
Diese Einstellungen sind dem Knoten settings untergeordnet.
<settings>
<players min="2" max="4" onehuman="false" withouthuman="true" order="lefttoright"/>
<rules class="mygame.game.MyRules"/>
<gamestate class="mygame.game.MyState" record="game"/>
<newgamedialog class="mygame.gui.MyNewDialog" asktosave="newgame.asktosave"/>
<gamedialogs class="mygame.gui.MyGameDialogs"/>
<infodialogs turn="false" round="true" game="true"/>
<interrupt round="true"/>
<delay round="500" turn="250" move="0"/>
<changed newgame="false" newround="true" newturn="false" aftermove="true"/>
<statistics games="true" scores="false" highscore="10" onlyfirst="true" scrollwhen="5" lowerscoreisbetter="false"/>
<zoom min="25" max="250"/>
<image welcome="/gfx/mygame.gif" timeout="1700"/>
<gamefield width="620" height="400" halign="left" valign="top"/>
<network port="1234" move="network" turn="network" round="network" game="network"/>
<hints path="/html" extension="html" move="" turn="" round="" game="hints.mygame" application="hints.myapplication"/>
<advertisements active="true" url="https://example.com/adservice.php?game=mygame&lang=[LANG]" errorpageurl="file:///android_asset/advertisement/defaultadvertisement.html" widthpercent="100" heightpercent="100" productid="no_ads"/>
</settings>
players: Grundeinstellungen für die Spieler. Gibt Mindest- und Maximalanzahl an. Das Attribut onehuman (optional) definiert, dass nur ein einziger menschlicher Spieler pro Computer spielen kann, der Wert muss hierfür true sein. Mit dem Attribut withouthuman kann festgelegt werden, ob Spiele ohne einem einzigen menschlichen Spieler erlaubt sind. Das Attribut order bestimmt, welche Reihenfolge die aktiven Spieler (im Gegensatz zu allen Spielern) an der Reihe sind, mögliche Werte sind lefttoright, clockwise und counterclockwise.rules: Definiert die Klasse, welche die Spielregeln implementiert, muss von tjger.game.GameRules abgeleitet sein.gamestate: Definiert die Klasse, welche den Spielzustand beinhaltet, muss die Schnittstelle tjger.game.GameState implementieren. Wenn das optionale Attribut record gesetzt ist (mögliche Werte sind game, round oder turn), ist es möglich, Spielstände aufzunehmen (siehe Spielstand debuggen).newgamedialog: Gibt den Dialog an, der beim Starten eines neuen Spiels angezeigt wird. Ist keiner definiert, wird der Dialog tjger.gui.NewGameDialog verwendet. Das Attribut asktosave (optional) gibt an, dass der Benutzer bestimmten kann, ob die Einstellungen gespeichert werden oder nicht, siehe dazu auch Zusätzliche Konfiguration ermöglichen.gamedialogs: Definiert eine Klasse vom Typ tjger.gui.GameDialogs mit deren Hilfe einzelne Dialoge (am Ende von Durchgängen, Runden oder Spielen) und die verschiedenen Karteireiter des Dialogs für Spielinformationen geändert werden können (siehe auch Die Standard-Dialoge).changed: Nachdem das Framework das Speichern automatisch übernimmt, kann hier definiert werden, nach welchen Aktionen ein Spielstand als geändert gelten soll. Mögliche Stellen sind newgame, newround, newturn und aftermove, welche im entsprechenden Fall auf true gesetzt werden müssen.statistics: Definiert, ob Statistiken gespeichert werden (optional). Wenn games auf true gesetzt ist, dann werden die gespielten und gewonnenen Spiele vermerkt. Ist scores auf true gesetzt, so behält ein Spieler seine Punkte auch über einzelne Spiele hinweg. Bei highscore kann ein numerischer Wert definiert werden, wie viele Höchstpunkte gespeichert werden. Mit dem Attribut onlyfirst kann definiert werden, ob immer nur der Gewinner in die Highscore-Liste aufgenommen wird (true) oder alle Spieler, die genug Punkte haben. Mit dem optionalen Attribut scrollwhen kann eine Anzahl von Zeilen festgelegt werden und im Dialog mit den Spielstatistiken erscheint ein vertikaler Scrollbar, wenn diese Anzahl überschritten wird. Mit dem optionalen Attribut lowerscoreisbetter kann definiert werden, ob eine niedrigere Punkteanzahl einen besseren Rang bedeutet (true). Dieses Attribut beeinflusst die Highscore-Liste und die Informationsdialoge am Ende eines Durchgangs, einer Runde und des Spiels.zoom: Definiert Minimum- und Maximalzoom. Ist kein Zoom definiert, so ist der Maßstab immer auf 100% gesetzt.image: Bei den Grundeinstellungen für Bilder kann ein Willkommens-Bild definiert werden, welches beim Starten der Anwendung erscheint. Optional ist es möglich, die Zeit (in Millisekunden) anzugeben, die das Bild mindestens angezeigt werden soll. Ist timeout nicht definiert, so wird der Wert standardmäßig auf 1700 Millisekunden gesetzt. Wenn es zu lang dauert bis das Bild erscheint, kann bereits beim HGBase-Framework in der Datei für die Einstellungen auch ein Willkommens-Bild gesetzt werden, wobei dort das Attribut welcomeImage so gesetzt wird wie das image-Attribute bei tjger und das Attribut welcomeImageBottom auf /tjger/gui/gfx/tjger2.jpg gesetzt werden sollte.gamefield: Mit den Attributen width und height kann die Standardgröße des Spielfelds definiert werden. Die wirkliche Größe des Spielfeldes ist aber noch abhängig vom aktuellen Spielbrett und dem aktuellen Hintergrund. Es wird immer die größte Höhe bzw. Breite verwendet. Mit den optionalen Attributen halign und valign kann die Ausrichtung vom Spielfeld innerhalb vom Fenster angegeben werden. Für die horizontale Ausrichtung (halign) sind die Werte left (default), center und right gültig. Für die vertikale Ausrichtung (valign) sind die Werte top (default), middle und bottom gültig.network: Ist notwendig, falls auch Netzwerkspiele möglich sein sollen. Dazu muss ein gültiger Standardport definiert werden. Zum Optimieren des Datentransfers kann auch definiert werden, welche reset-Methoden des Spielstandes lokal behandelt werden sollen. Dazu werden die Attribute move, turn, round oder game auf local gesetzt. Ansonsten wird bei der jeweiligen reset-Methode der gesamte Spielstand übertragen.infodialogs: Definiert an welchen Stellen ein Informationsdialog über den Spielstand angezeigt werden soll. Mögliche Stellen sind nach turn, round und game, wobei diese Attribute auf true gesetzt werden. Der Inhalt der Dialoge kann in der beim Element gamedialogs definierten Klasse geändert werden.interrupt: Wird das Attribut round auf true gesetzt, so wird der Spielablauf nach jeder Runde unterbrochen und muss selbständig duch Aufruf der Methode newRound() der GameEngine fortgesetzt werden.delay: Definiert Verzögerungen in Millisekunden zwischen Runden (round), Spieldurchgängen (turn) und Spielzügen (move). Diese Verzögerung ist jeweils vor der Aktion (z.B. Beginn eines neuen Spieldurchgangs), außer vor dem ersten Auftreten dieser Aktion im jeweiligen Kontext (d.h. vor dem ersten Spieldurchgang einer Runde gibt es z.B. keine Verzögerung). Es gibt ein spezielles Menü vom Typ gamespeed, mit dem ein Menü für die Spielgeschwindigkeit (langsam, normal, schnell) erzeugt wird und die Verzögerung entsprechend anpasst. Für alle automatisch erzeugten Menüpunkte gibt es bereits Standardtexte.hints: Erlaubt das automatische Anzeigen von Spielhinweisen ("Tip of the day"). Das Attribut path definiert den generellen Ursprungspfad, wo diese Dateien zu finden sind, extension die Dateiendung. Die anderen Attribute definieren, wann der Spielhinweis erscheinen soll: Gleich nach Start der Applikation (application), am Beginn eines Spieles (game), am Beginn jeder Runde (round), am Beginn jeden Durchgangs (turn) oder vor jedem Spielzug eines menschlichen Spielers (move). Für den dabei gesetzten Attributwert muss in der Datei für Meldungen der Dateiname (inklusive eines eventuell relativen Pfades) sprachenabhängig definiert werden. Die Dateien müssen dabei zusätzlich durchnumeriert sein. Ein Beispiel für die obigen Einstellung wäre eine Meldung: <msg code="hints.game">de/game</msg> und einer Datei /html/hints/de/game0.html.advertisements: Nur für Android Applications verfügbar!active gleich true ist, dann wird nach jedem Spiel die über das Attribut url definierte Werbung angezeigt. Über den Platzhalter [LANG] kann auf die aktuelle Sprache der App zugegriffen werden, damit Werbungen in der gleichen Sprache dargestellt werden können.errorpageurl verwendet. Dies könnte z.B. eine lokale Datei sein (über file://android_assest/ kann auf das assets-Verzeichnis zugegriffen werden).widthpercent und heightpercent kann angegeben werden, wie viel Prozent des Bildschirms für die Anzeige der Werbung verwendet wird.productid kann die ID ein Produkts für In-App-Purchases angegeben werden. Der Wert muss der ID des Produkts in der Google Play Console entsprechen. Wenn eine Produkt-ID angegeben ist, dann wird auf der Hauptmaske ein "Werbung entfernen"-Icon angezeigt (Ressource ic_remove_ads.png). Über das Icon wird der Kaufprozess angestoßen. Wenn das Produkt erfolgreich gekauft wurde, dann wird das Icon nicht mehr angezeigt und es wird keine Werbung mehr angezeigt.Einige der generellen Einstellungen können auch während dem Spiel dynamisch geändert werden. Dies geschieht mittels set-Methoden der Klasse GameConfig.
Der Knoten players enthält einige grafische Informationen über die Spieler, die einzelnen Unterknoten player definieren verschiedene Spielertypen.
<players extension="gif" path="/gfx/player" playerimage="player" piececolor="piece">
<player type="type.human" class="tjger.game.HumanPlayer" image="/gfx/player/type.human.gif"/>
<player type="type.computer" class="sample.game.ComputerPlayer"/>
<player type="type.network" class="tjger.game.NetworkPlayer"/>
</players>
extension: Dateierweiterung für die Bilder von Spielern und den Bildern der Spielertypen.path: Pfad zu den Bildern von Spielern und Spielertypen.playerimage: Präfix der Bilder für die Spieler. Die Bilder werden wie folgt gesucht: <path>/<playerimage><0..n>.<extension>, zum Beispiel: /gfx/player/player1.gif.piececolor: Präfix für den Namen von Spielfiguren, welche den Spielern zugeordnet werden. Die Figuren werden beim Spielmaterial definiert. Die Farben für die Figuren von Spielern haben das Format <piececolor><0..n>, z.B. piece0. Wenn es keine Figur mit dieser Farbe gibt, so werden alle Kartensets danach durchsucht.player: Für jeden Spielertyp wird der Name des Typs und die implementierende Klasse angegeben. Die Klassen müssen von tjger.game.GamePlayer abgeleitet sein (bzw. HumanPlayer oder NetworkPlayer falls es sich um einen menschlichen Spieler oder einen Netzwerkgegner handeln soll, Details siehe Klassen für den Spielablauf). Für die einzelnen Typen muss eine Meldung definiert sein. Optional kann auch der Pfad zu einem Bild für den Spielertyp angegeben werden, ist dies nicht der Fall, so wird das Bild als folgende Datei gesucht: <path>/<type>.<extension>, z.B. /gfx/player/type.human.gif.Für die verschiedenen Sorten des Spielmaterials gibt es verschiedene Bereiche:
backgrounds)boards)pieces)covers)cards)parts)colors)arrangements)Bei allen Spielmaterialien kann bestimmt werden, ob die jeweiligen Elemente im Dialog zum Ändern der Zusammenstellungen angezeigt werden, oder vor dem Benutzer versteckt werden. Das Schlüsselwort hierzu ist hidden, das entweder auf false oder true gesetzt wird. Sinn macht das Setzen auf false dann, wenn z.B. einige Spielbretter versteckt werden, aber einzelne angezeigt werden sollen. Der Entwickler kann sowohl auf die versteckten als auch die sichtbaren Materialen zugreifen. Versteckte Materialen können aber nie aktiv sein, dies betrifft vor allem Methoden von GameConfig: so werden z.B. versteckte Spielbretter bei getBoards() zurückgegeben, bei getActiveBoard() kann es sich hingegen nie um ein verstecktes Spielbrett handeln. Die Benutzerdefinierten Farben können nicht versteckt werden, weil das keinen Sinn ergeben würde.
Alle Spielmaterialien, die ein Bild enthalten, können auch einen Schatten definieren. Dies wird durch das Attribut shadow gekennzeichnet, dass entweder auf true gesetzt wird (unter Verwendung der Standardwerte) oder indem die x- und y-Distanz definiert wird (z.B. 10;10) bzw. zusätzlich der Alpha-Wert als eine Zahl zwischen 0 und 1 (z.B. 10;10;0.5). Das Attribut für den Schatten kann entweder auf einem einzelnen Element oder aber auch auf höhere Ebene (z.B. für alle Karten) definiert werden. Zusätzlich gibt es eine Einstellung drawshadows, die bestimmt, ob solche Schatten gezeichnet werden sollen (der vorgesehene Menüpunkt-Eintrag dafür lautet settings.drawshadows).
Alle Spielmaterialien, die ein Bild enthalten, können zudem auch eine Reflektion definieren. Dies wird durch das Attribut reflection gekennzeichnet, dass entweder auf true gesetzt wird (unter Verwendung der Standardwerte) oder indem der vertikale Abstand definiert wird (z.B. 5) bzw. zusätzlich der der Anteil des Bildes größer 0 und kleiner gleich 1 und der Alpha-Wert mit dem die Reflektion gestartet werden soll als eine Zahl zwischen 0 und 1 (z.B. 5;0.5;0.5). Das Attribut für eine Reflektion kann entweder auf einem einzelnen Element oder aber auch auf höhere Ebene (z.B. für alle Karten) definiert werden. Zusätzlich gibt es eine Einstellung drawreflections, die bestimmt, ob solche Spiegelungen gezeichnet werden sollen (der vorgesehene Menüpunkt-Eintrag dafür lautet settings.drawreflections).
Hinweis für Android Applications
In Android ist es möglich, dass einzelne Spielmaterialien, Sets von Spielmaterialien oder Zusammenstellungen erst über In-App-Purchases gekauft werden müssen. Dazu muss beim entsprechenden Spielmaterial, Sets von Spielmaterialien oder Zusammenstellung das Attribut productid angegeben werden. Der Wert muss der ID des Produkts in der Google Play Console entsprechen. Mehrere Spielmaterialien, Sets von Spielmaterialien oder Zusammenstellungen können die gleiche Produkt-ID haben.
Es wird dann in der Auswahlliste neben dem Spielmaterial ein 🔒-Symbol angezeigt (Text-Ressource unpurchased_marker). Wenn ein solches Element ausgewählt wird, dann wird der Kaufprozess angestoßen. Wird der Kauf erfolgreich abgeschlossen, dann wird das Symbol entfernt und das Spielmaterial kann verwendet werden.
Solange ein nicht gekauftes Element ausgewählt ist, kann kein Spiel gestartet werden.
Beispiel:
<backgrounds extension="jpg" path="/gfx/background">
<background name="wood"/>
<background name="carpet" productid="oriental_theme"/>
<background name="stone" productid="medieval_theme"/>
</backgrounds>
<boards extension="jpg" path="/gfx/board">
<board name="plastic"/>
<board name="glass" productid="oriental_theme"/>
<board name="marble" productid="medieval_theme"/>
</boards>
Als Hintergrund kann entweder ein Bild oder eine Farbe verwendet werden. Bei einem Bild wird angegeben, ob es nur einmal gezeichnet wird oder wiederholt wird, bis es die ganze Fläche ausfüllt. Bei einem farbigen Hintergrund wird eine Standardfarbe angegeben:
<backgrounds extension="jpg" path="/gfx/background">
<background name="back.green" image="/gfx/background/back.green.jpg" zoom="100"/>
<background name="back.red" repeat="true" hidden="true"/>
<background name="back.red" repeat="true" ignorezoom="true"/>
<background name="back.color" color="40960"/>
<background name="back.white" color="16777215" fixed="true"/>
</backgrounds>
extension: Dateierweiterung für Hintergrundbilder.path: Verzeichnis, in dem die Hintergrundbilder gesucht werden.background: Definiert einen Hintergrund. Der Name (name) muss eindeutig sein und wenn der Hintergrund nicht versteckt ist, muss eine Meldung für den Namen definiert sein. Für Bilder wird entweder das Attribute image verwendet oder kein Attribut angegeben. Im zweiten Fall wird dann die Datei <path>/<name>.<extension> gesucht, z.B. /gfx/background/back.green.jpg. Optional kann noch das Attribut repeat angegeben werden, damit das Bild so oft gezeichnet wird, damit es den Hintergrund ganz ausfüllt. Mit dem zusätzlichen Attribut ignorezoom kann bei so einem Hintergrund eingestellt werden, dass das Bild nicht gezoomt wird (dies macht nur bei einem Bild Sinn, dass wiederholt gezeichnet wird). Mit der Option zoom wird ein Bild standardmäßig entsprechend dem angegebenen Wert skaliert; außer das Bild soll wiederholt werden und ignorezoom ist gesetzt, dann wird der Wert nicht weiter verwendet. Für einen einfärbigen Hintergrund muss eine Farbe mit dem Attribut color defniert werden. Dabei wird der hexadezimale Code in eine Dezimalzahl umgerechnet, also z.B. die Farbe #00A000 in 40960. Mit dem Attribut fixed (und dem Wert true) wird bestimmt, dass der Benutzer die Farbe nicht ändern darf, ansonsten ist es möglich, im Dialog für die Zusammenstellung des Spielmaterials frei eine Farbe zu definieren.Spielbretter sind in jedem Fall Bilder. Die Definition erfolgt ähnlich wie bei den Hintergrundbildern:
<boards extension="jpg" path="/gfx/board" hidden="true">
<board name="board.wood" image="/gfx/board/board.wood.jpg" xpos="20" ypos="20" />
<board name="board.glass" zoom="80"/>
<board name="board.marble" hidden="true"/>
</boards>
extension: Dateierweiterung für die Bilder der Spielbretter.path: Verzeichnis, in dem die Bilder gesucht werden.board: Definiert ein einzelnes Spielbrett. Der Name (name) muss eindeutig sein und wenn das Spielbrett nicht versteckt ist, muss eine Meldung für den Namen definiert sein. Optional kann das Attribut image gesetzt werden, ansonsten wird die Datei <path>/<name>.<extension> für das Bild verwendet. Zudem kann eine x- und eine y-Position angegeben werden, an der sich das linke obere Eck des Bildes befinden soll. Die Option zoom erlaubt es, die Standardskalierung für das entsprechende Bild des Spielbrettes zu setzen.Bei den Spielfiguren werden sogenannte Figuren-Sets definiert. Wobei ein Set aus mehreren Farben mit jeweils mehreren Figuren besteht. Mit der Option orderby kann festgelegt werden, ob zuerst nach Farben (color), Werten (value) oder ob gar nicht (none) sortiert werden soll (eine andere Sortierung ist auch mittels GameManager.setPartSorter möglich):
<pieces extension="gif" path="/gfx/pieces">
<pieceset name="piece.old">
<piece color="piece0" sequence="1" image="/gfx/pieces/piece.old/piece0-1.gif"/>
<piece color="piece0" sequence="2"/>
<piece color="piece1" sequencestart="1" sequenceend="2"/>
<piece color="dice" sequence ="0"/>
</pieceset>
<pieceset name="piece.new" hidden="true">
<piece color="piece0" sequencestart="1" sequenceend="2" value="0"/>
<piece color="piece1" sequencestart="1" sequenceend="2"/>
<piece color="dice" sequence ="0" value="7"/>
</pieceset>
</pieces>
extension: Dateierweiterung für die Bilder der einzelnen Spielfiguren.path: Verzeichnis, in dem die Bilder gesucht werden.pieceset: Ein Set benötigt einen eindeutigen Namen (name) und wenn das Figuren-Set nicht versteckt ist, muss eine Meldung für den Namen definiert sein.piece: Gibt entweder eine einzelne Spielfigur oder einen Bereich einer Farbe an. Die Farbe wird mit dem Attribut color definiert, wobei Farbe eher als abstrakter Begriff zu verstehen ist. Für eine einzelne Figur wird das Attribut sequence definiert, für einen Sequenzbereich gibt es die Attribute sequencestart und sequenceend (alle Angaben müssen numerisch sein). Es kann auch die Datei für ein Bild mittels image definiert werden, ansonsten werden die Dateien im folgenden Format gesucht: <path>/<name>/<color>-<sequence>.<extension> (sequence steht hierbei auch für einen einzelnen Wert des Sequenzbereichs), z.B.: /gfx/pieces/piece.old/dice-0.gif . Wenn ein Bild bei einem Sequenzbereich definiert ist, bekommen alle Elemente das gleiche Bild. Zusätzlich zum Attribut sequence, welches pro Farbe eindeutig sein muss, kann auch noch ein Wert für eine Spielfigur mit dem Attribut value festgelegt werden. Ist dieses Attribut nicht definiert, so ist dieser Wert gleich der Sequenz-Nummer. Es ist auch möglich, für einen Sequenzbereich einen einheitlichen Wert zu definieren.Für die Deckblätter werden einfach Bilder definiert. Dies funktioniert genauso wie bei den Spielbrettern, mit dem Unterschied, dass es keine optionalen Attribute für x- und y-Positionen gibt. Das folgende Beispiel sollte daher selbsterklärend sein:
<covers extension="png" path="/gfx/cover">
<cover name="cover.blue" image="/gfx/cover/cover.blue.png"/>
<cover name="cover.red"/>
</covers>
Das Definieren der Spielkarten funktioniert genauso wie die Definition von Spielfiguren. Allerdings gibt es für die Spielkarten bereits zahlreiche nützliche Methoden, wie z.B. Karten mischen, austeilen oder aber auch Hilfsmethoden zum Speichern von Karten (siehe auch CardUtil, PartUtil, PlayerCardMap, NetworkUtil und XmlUtil). Typische Farben der Karten sind z.B. Herz oder Kreuz. Mit der Option orderby kann festgelegt werden, ob zuerst nach Farben (color), Werten (value) oder ob gar nicht (none) sortiert werden soll (eine andere Sortierung ist auch mittels GameManager.setPartSorter möglich):
<cards extension="gif" path="/gfx/cardset" orderby="color">
<cardset name="cards.normal">
<card color="joker" sequence="1" value="15" image="/gfx/cardset/cards.normal/joker-1.gif"/>
<card color="joker" sequence="2" value="15"/>
<card color="joker" sequence="3" value="15"/>
<card color="hearts" sequence="1" value="14"/>
<card color="hearts" sequencestart="2" sequenceend="13"/>
</cardset>
<cardset name="cards.vector">
<card color="joker" sequencestart="1" sequenceend="3" value="15"/>
<card color="hearts" sequence="1" value="14"/>
<card color="hearts" sequencestart="2" sequenceend="13"/>
</cardset>
</cards>
Standardmäßig gibt es nur eine Sorte Kartenset, für das es aber unterschiedliche Ausprägungen geben kann (z.B. modern oder klassisch). Um auch unterschiedliche Kartensets zu verwenden und dafür auch andere Ausprägungen einzustellen (z.B. moderne Zahlenkarten und klassische Buchstabenkarten), ist es auch möglich bei jedem Kartenset die Zugehörigkeit zu einem Typen anzugeben. Das wird mit dem Attribut type bei Eintrag cardset festgelegt. Der Name für das Standard-Kartensettyp ist unter ConstantValue.CONFIG_CARDSET definiert und muss nicht angegeben werden. Von der Syntax ist dies genau gleich wie bei den benutzerdefinierten Sets (siehe weiter unten). Durch ein Attribut orderby beim cardset-Eintrag kann auch die Sortierung für die unterschiedlichen Typen abweichend von der Standardsortierung angegeben werden.
<cards extension="gif" path="/gfx/cardset" orderby="color">
<cardset name="cards.normal">
...
</cardset>
<cardset name="cards.vector">
...
</cardset>
<cardset type="cardset.joker" name="joker.normal" orderby="value">
<card color="default" sequencestart="1" sequenceend="3"/>
</cardset>
<cardset type="cardset.joker" name="joker.vector">
<card color="default" sequencestart="1" sequenceend="3"/>
</cardset>
</cards>
Als benutzerdefinierte Objekte können sowohl einzelne Materialien als auch Sets definiert werden. Für die Materialien wird ein Typ definiert. Alle Objekte desselben Typs gehören zusammen und sind Alternativen im Dialog für die Zusammenstellung des Spielmaterials. Pro Typ gibt es in diesem Dialog dann eine Combobox. Für die Typen müssen auch Meldungen in der Datei für Meldungen definiert werden. Der Name dieser benutzerdefinierten Typen darf auf keinen Fall mit den Typbezeichnungen der Standardmaterialien übereinstimmten, welche alle mit game. beginnen (game.background, game.board, ...). Werden einzelne Objekte definiert, so beinhalten diese nur jeweils ein Bild (analog z.B. zu Deckblättern). Werden Sets definiert, so werden diese analog zu Spielfiguren bzw. Spielkarten definiert:
<parts extension="gif" path="/gfx/parts">
<part type="sample.decoration" name="decoration.candle"/>
<part type="sample.decoration" name="decoration.flower"/>
<part type="sample.decoration" name="decoration.none"/>
<partset type="sample.counter" name="counter.normal" orderby="none">
<part color="counter" sequencestart="1" sequenceend="10"/>
</partset>
<partset type="sample.counter" name="counter.modern">
<part color="counter" sequencestart="1" sequenceend="10"/>
</partset>
</parts>
Es besteht zusätzlich die Möglichkeit, die benutzerdefinierten Objekte durch selbst implementierte Klassen zu ersetzen. Diese müssen von den jeweils vorgesehenen Klassen abgeleitet sein und auch denselben Konstruktor besitzen. Für Klassen von part (partclass) ist das
tjger.gui.completed.Part, für partset (setclass) ist das tjger.gui.completed.PartSet und für part, die Teil eines partset sind (cvpclass) ist das tjger.gui.completed.ColorValuePart. Die eigenen Klassen werden mittels eigener Knoten definiert (Erweiterung des obigen Beispiels):
<parts extension="gif" path="/gfx/parts">
<extend type="sample.decoration" partclass="sample.gui.parts.SamplePart"/>
<extend type="sample.counter" setclass="sample.gui.parts.SamplePartSet" cvpclass="sample.gui.parts.SampleColorValuePart"/>
<part type="sample.decoration" name="decoration.candle"/>
<part type="sample.decoration" name="decoration.flower"/>
<part type="sample.decoration" name="decoration.none"/>
<partset type="sample.counter" name="counter.normal" orderby="none">
<part color="counter" sequencestart="1" sequenceend="10"/>
</partset>
...
</parts>
Die Farben werden nur mittels Typ und optional einer Standardfarbe definiert (default). Wenn eine Standardfarbe angegeben ist (in der Art wie die Farbe beim Hintergrund), dann öffnet der Dialog zum Auswählen der Farben mit dieser Farbe, ansonsten mit der aktuell gewählten Farbe.
<colors>
<color type="sample.colorA" default="40960"/>
<color type="sample.colorB"/>
</colors>
Als letztes können auch diverse Zusammenstellungen des Spielmaterials definiert werden. Hier kann angegeben werden, welche Hintergründe, Spielbretter etc. zusammengehören. Solche Zusammenstellungen machen nur Sinn, wenn der Dialog für das Ändern der Zusammenstellungen erreichbar ist (Menübefehl settings.parts). Die Standardmaterialien werden als Attribute angegeben, für benutzerdefinierte Objekte gibt es Unterknoten:
<arrangements complete="false">
<arrangement name="arrange.standard" background="back.green" board="board.glass" pieceset="piece.old" cover="cover.red.vector" cardset="cards.vector">
<cardset type="cardset.joker" value="joker.normal"/>
<part type="sample.decoration" value="decoration.candle"/>
<partset type="sample.counter" value="counter.modern"/>
<color type="sample.colorA" value="16777215"/>
</arrangement>
<arrangement name="arrange.new" background="back.color" board="board.glass" pieceset="piece.new" cover="cover.blue.vector" cardset="cards.vector"/>
</arrangements>
complete: (Optional) Bestimmt, ob nur die definierten Zusammenstellungen möglich sind, oder ob der Benutzer die Zusammenstellungen auch beliebig abändern kann. Falls complete auf true gesetzt ist, können die Zusammenstellungen nicht abgeändert werden. In diesem Fall sollten also die einzelnen Zusammenstellungen komplett sein, also alle vorkommenden Spielmaterialien beachten. Standardmäßig ist das Abändern möglich.arrangement: Jede Zusammenstellung wird durch einen eindeutigen Namen (name) identifiziert. Für diesen Namen sollte auch eine Meldung definiert sein. Des weiteren werden die einzelnen Spielmaterialien definiert, welche in der jeweiligen Zusammenstellung vorkommen. Hierfür wird pro Spielmaterial (background, board, pieceset, cover, cardset) der entsprechende Name angegeben. Es müssen nicht notwendigerweise alle Materialien angegeben werden.cardset: Wurde ein Kartenset mit einen speziellen Typ definiert, so kann dieser hier in eine Zusammenstellung aufgenommen werden.part: Für jeden benutzerdefinierten Typ kann ein Eintrag gemacht werden, wobei das Attribut type den Typ bestimmt und das Attribut value den Namen des zu der Zusammenstellung gehöhrenden Elements.partset: Für benutzerdefinierte Sets können Einträge analog wie für benutzerdefinierte Einzelobjekte gemacht werden.color: Für die frei wählbaren Farben kann pro Farbe ein Eintrag bei den benutzerdefinierten Sets gemacht werden.Die definierten Elemente (mit Ausnahme vom Hintergrundbild und vom Spielbrett) können über zwei Arten am Spielfeld positioniert werden:
GamePanel abgeleitet werden. Die Positionierung der Elemente muss vollständig in Java erfolgen (siehe Methode paintParts(...)).ConfigurableGamePanel abgeleitet werden (siehe konfigurierbares Game Panel). Die Positionierung der Elemente erfolgt in der Konfigurationsdatei. Es ist aber zusätzlich möglich programmatisch Einfluss zu nehmen.Die Konfiguration erfolgt über den Knoten gamefieldlayout. Dieser Knoten unterstützt folgende Attribute:
margintop: Hiermit wird der obere Abstand zum Spielfeldrand definiert. Die Angabe muss als numerischer Wert in Pixel erfolgen. Alle vertikalen Positionsangaben berücksichtigen diesen. Beispiel: Wenn als Abstand 10 und für ein Element die y-Postion 15 angegeben wird, dann wird das Element 25 Pixel vom oberen Spielfeldrand positioniert. Standard ist 0.marginbottom: Hiermit wird der untere Abstand zum Spielfeldrand definiert. Die Angabe muss als numerischer Wert in Pixel erfolgen. Dies ist nur für Positionsangaben mittels bottom oder middle relevant. Standard ist 0.marginleft: Hiermit wird der linke Abstand zum Spielfeldrand definiert. Die Angabe muss als numerischer Wert in Pixel erfolgen. Alle horizontalen Positionsangaben berücksichtigen diesen. Beispiel: Wenn als Abstand 10 und für ein Element die x-Postion 15 angegeben wird, dann wird das Element 25 Pixel vom linken Spielfeldrand positioniert. Standard ist 0.marginright: Hiermit wird der rechte Abstand zum Spielfeldrand definiert. Die Angabe muss als numerischer Wert in Pixel erfolgen. Dies ist nur für Positionsangaben mittels right oder center relevant. Standard ist 0.In einem Layout können Bereiche (areas) definiert werden. Ein Bereich kann für die Positionierung von Elementen verwendet werden.
Ein Bereich (area) unterstützt folgende Attribute:
name: Der Name des Bereichs.xpos: Die x-Position des Bereichs auf dem Spielfeld (unter Berücksichtigung vom linken Abstand vom Spielfeldrand). Die Angabe muss als numerischer Wert in Pixel oder als Prozentwert (als Zahl mit anschließendem %) erfolgen oder einer der folgenden Werte sein: left, right oder center, womit der Bereich linksbündig, rechtsbündig oder zentriert positioniert werden kann.ypos: Die y-Position des Bereichs auf dem Spielfeld (unter Berücksichtigung vom oberen Abstand vom Spielfeldrand). Die Angabe muss als numerischer Wert in Pixel oder als Prozentwert (als Zahl mit anschließendem %) erfolgen oder einer der folgenden Werte sein: top, bottomoder middle, womit der Bereich oben, unten oder mittig positioniert werden kann.width: Die Breite des Bereichs. Die Angabe muss als numerischer Wert in Pixel erfolgen oder als Prozentwert (als Zahl mit anschließendem %). Die Prozentangabe bezieht sich auf die Breite des Spielfelds (unter Berücksichtigung der Abstände zum linken und rechten Spielfeldrand).height: Die Höhe des Bereichs. Die Angabe muss als numerischer Wert in Pixel erfolgen oder als Prozentwert (als Zahl mit anschließendem %). Die Prozentangabe bezieht sich auf die Höhe des Spielfelds (unter Berücksichtigung der Abstände zum oberen und unteren Spielfeldrand).margintop: Hiermit der obere Abstand innerhalb vom Bereich definiert. Die Angabe muss als numerischer Wert in Pixel erfolgen oder als Prozentwert (als Zahl mit anschließendem %). Die Prozentangabe bezieht sich auf die Höhe des Bereichs. Alle vertikalen Positionsangaben berücksichtigen diesen. Beispiel: Wenn als Abstand 10 und für ein Element die y-Position 15 angegeben wird, dann wird das Element 25 Pixel vom oberen Bereichsrand positioniert.marginbottom: Hiermit wird der untere Abstand innerhalb vom Bereich definiert. Die Angabe muss als numerischer Wert in Pixel erfolgen oder als Prozentwert (als Zahl mit anschließendem %). Die Prozentangabe bezieht sich auf die Höhe des Bereichs. Dies ist nur für Positionsangaben mittels bottom oder middle relevent.marginleft: Hiermit wird der linke Abstand innerhalb vom Bereich definiert. Die Angabe muss als numerischer Wert in Pixel erfolgen oder als Prozentwert (als Zahl mit anschließendem %). Die Prozentangabe bezieht sich auf die Breite des Bereichs. Alle horizontalen Positionsangaben berücksichtigen diesen. Beispiel: Wenn als Abstand 10 und für ein Element die x-Position 15 angegeben wird, dann wird das Element 25 Pixel vom linken Bereichsrand positioniert.marginright: Hiermit wird der rechte Abstand innerhalb vom Bereich definiert. Die Angabe muss als numersicher Wert in Pixel erfolgen oder als Prozentwert (als Zahl mit anschließendem %). Die Prozentangabe bezieht sich auf die Breite des Bereichs. Dies ist nur für Positionsangaben mittels right oder center relevant.hidden: Hiermit wird bestimmt, ob der Bereich selbst angezeigt werden soll (als Rechteck). Gültige Werte sind true oder false. Standard ist false. Die Einstellung true ist eher für Debuging-Zwecke, um zu sehen, ob der Bereich an der gewünschten Stelle ist.In einem Layout können Elemente (elements) definiert werden, welche auf dem Spielfeld dargestellt werden sollen. Die Elemente sind die definierten Spielmaterialien.
Für folgende Spielmaterialien kann das Layout konfiguriert werden:
Ein Set von Figuren (pieceset) unterstützt folgende Attribute:
xpos: Die x-Position der Figuren auf dem Spielfeld (unter Berücksichtigung vom linken Abstand vom Spielfeldrand bzw. Bereichsrand). Die Angabe muss als numerischer Wert in Pixel oder als Prozentwert (als Zahl mit anschließendem %) erfolgen oder einer der folgenden Werte sein: left, right oder center, womit die Figuren linksbündig, rechtsbündig oder zentriert positioniert werden können.ypos: Die y-Position der Figuren auf dem Spielfeld (unter Berücksichtigung vom oberen Abstand vom Spielfeldrand bzw. Bereichsrand). Die Angabe muss als numerischer Wert in Pixel oder als Prozentwert (als Zahl mit anschließendem %) erfolgen oder einer der folgenden Werte sein: top, bottomoder middle, womit die Figuren oben, unten oder mittig positioniert werden können.percentsize: Die prozentuelle Größe in welcher die Bilder der Figuren dargestellt werden. Die Angabe muss als numerischer Wert erfolgen (ohne anschließendem %) oder einer der folgenden Werte sein: scale, scale_x oder scale_y. Bei der Prozentangabe bedeutet der Wert 100 die Normalgröße. Bei den Skalierungsvarianten werden die Figuren so skaliert (unter Beibehaltung des Seitenverhältnisses), dass sie das Spielfeld bzw. den Bereich horizontal (bei scale_x) oder vertikal (bei scale_y) ausfüllen. Bei scale wird so skaliert, dass die Figuren das Spielfeld bzw. den Bereich soweit wie möglich ausfüllen ohne darüber hinaus zu ragen.angle: Der Grad der Drehung mit welchem die Figuren dargestellt werden sollen. Die Angabe muss als numerischer Wert erfolgen. Standard ist 0.area: Der Name des Bereichs, in welchem die Figuren dargestellt werden sollen. Wenn ein Bereich angegeben ist, dann beziehen sich die Positionsangaben auf den Bereich - ansonsten auf das Spielfeld.xspacing: Der horizontale Versatz der einzelnen Figuren. Die Angabe muss als numerischer Wert in Pixel erfolgen.yspacing: Der vertikale Versatz der einzelnen Figuren. Die Angabe muss als numerischer Wert in Pixel erfolgen.orientation: Die Richtung in welcher die Figuren dargestellt werden sollen. Folgende Werte sind gültig: ltr_down (von links nach rechts und dann nach unten), ltr_up (von links nach rechts und dann nach oben), down_ltr (von oben nach unten und nach rechts), up_ltr (von unten nach oben und dann nach rechts), rtl_down (von rechts nach links und dann nach unten), rtl_up (von rechts nach links und dann nach oben), down_rtl (von oben nach unten und dann nach links) oder up_rtl (von unten nach oben und dann nach links).wrapthreshold: Bestimmt nach wie vielen Figuren umgebrochen werden soll. Dieser Wert ist nur relevant, wenn orientation angegeben wurde.Ein Set von Karten (cardset) unterstützt folgende Attribute:
type: Der Typ des Kartensets. Für das Standard-Kartenset muss der Typ nicht angegeben werden.playerindex: Der Index des Spielers, für welchen die Karten angezeigt werden sollen. Die Angabe muss als numerischer Wert erfolgen. Der erste Spieler hat den Index 0.xpos: Die x-Position der Karten auf dem Spielfeld (unter Berücksichtigung vom linken Abstand vom Spielfeldrand bzw. Bereichsrand). Die Angabe muss als numerischer Wert in Pixel oder als Prozentwert (als Zahl mit anschließendem %) erfolgen oder einer der folgenden Werte sein: left, right oder center, womit die Karten linksbündig, rechtsbündig oder zentriert positioniert werden können.ypos: Die y-Position der Karten auf dem Spielfeld (unter Berücksichtigung vom oberen Abstand vom Spielfeldrand bzw. Bereichsrand). Die Angabe muss als numerischer Wert in Pixel oder als Prozentwert (als Zahl mit anschließendem %) erfolgen oder einer der folgenden Werte sein: top, bottomoder middle, womit die Karten oben, unten oder mittig positioniert werden können.percentsize: Die prozentuelle Größe in welcher die Bilder der Karten dargestellt werden. Die Angabe muss als numerischer Wert erfolgen (ohne anschließendem %) oder einer der folgenden Werte sein: scale, scale_x oder scale_y. Bei der Prozentangabe bedeutet der Wert 100 die Normalgröße. Bei den Skalierungsvarianten werden die Karten so skaliert (unter Beibehaltung des Seitenverhältnisses), dass sie das Spielfeld bzw. den Bereich horizontal (bei scale_x) oder vertikal (bei scale_y) ausfüllen. Bei scale wird so skaliert, dass die Karten das Spielfeld bzw. den Bereich soweit wie möglich ausfüllen ohne darüber hinaus zu ragen.angle: Der Grad der Drehung mit welchem die Karten dargestellt werden sollen. Die Angabe muss als numerischer Wert erfolgen. Standard ist 0.area: Der Name des Bereichs, in welchem die Karten dargestellt werden sollen. Wenn ein Bereich angegeben ist, dann beziehen sich die Positionsangaben auf den Bereich - ansonsten auf das Spielfeld.xspacing: Der horizontale Versatz der einzelnen Karten. Die Angabe muss als numerischer Wert in Pixel erfolgen.yspacing: Der vertikale Versatz der einzelnen Karten. Die Angabe muss als numerischer Wert in Pixel erfolgen.orientation: Die Richtung in welcher die Karten dargestellt werden sollen. Folgende Werte sind gültig: ltr_down (von links nach rechts und dann nach unten), ltr_up (von links nach rechts und dann nach oben), down_ltr (von oben nach unten und nach rechts), up_ltr (von unten nach oben und dann nach rechts), rtl_down (von rechts nach links und dann nach unten), rtl_up (von rechts nach links und dann nach oben), down_rtl (von oben nach unten und dann nach links) oder up_rtl (von unten nach oben und dann nach links).wrapthreshold: Bestimmt nach wie vielen Karten umgebrochen werden soll. Dieser Wert ist nur relevant, wenn orientation angegeben wurde.covered: Legt fest, ob die Karten mit der Rückseite nach oben angezeigt werden sollen. Folgende Werte sind gültig: true oder false.Ein Objekt (part) unterstützt folgende Attribute:
type: Der Typ des Objekts.xpos: Die x-Position des Objekts auf dem Spielfeld (unter Berücksichtigung vom linken Abstand vom Spielfeldrand bzw. Bereichsrand). Die Angabe muss als numerischer Wert in Pixel oder als Prozentwert (als Zahl mit anschließendem %) erfolgen oder einer der folgenden Werte sein: left, right oder center, womit das Objekt linksbündig, rechtsbündig oder zentriert positioniert werden kann.ypos: Die y-Position des Objekts auf dem Spielfeld (unter Berücksichtigung vom oberen Abstand vom Spielfeldrand bzw. Bereichsrand). Die Angabe muss als numerischer Wert in Pixel oder als Prozentwert (als Zahl mit anschließendem %) erfolgen oder einer der folgenden Werte sein: top, bottomoder middle, womit das Objekt oben, unten oder mittig positioniert werden kann.percentsize: Die prozentuelle Größe in welcher das Bild vom Objekt dargestellt wird. Die Angabe muss als numerischer Wert erfolgen (ohne anschließendem %) oder einer der folgenden Werte sein: scale, scale_x oder scale_y. Bei der Prozentangabe bedeutet der Wert 100 die Normalgröße. Bei den Skalierungsvarianten wird das Objekt so skaliert (unter Beibehaltung des Seitenverhältnisses), dass es das Spielfeld bzw. den Bereich horizontal (bei scale_x) oder vertikal (bei scale_y) ausfüllt. Bei scale wird so skaliert, dass das Objekt das Spielfeld bzw. den Bereich soweit wie möglich ausfüllt ohne darüber hinaus zu ragen.angle: Der Grad der Drehung mit welchem das Objekt dargestellt werden soll. Die Angabe muss als numerischer Wert erfolgen. Standard ist 0.area: Der Name des Bereichs, in welchem das Objekt dargestellt werden soll. Wenn ein Bereich angegeben ist, dann beziehen sich die Positionsangaben auf den Bereich - ansonsten auf das Spielfeld.Ein Set von Objekten (partset) unterstützt folgende Attribute:
type: Der Typ des Sets.xpos: Die x-Position der Objekte auf dem Spielfeld (unter Berücksichtigung vom linken Abstand vom Spielfeldrand bzw. Bereichsrand). Die Angabe muss als numerischer Wert in Pixel oder als Prozentwert (als Zahl mit anschließendem %) erfolgen oder einer der folgenden Werte sein: left, right oder center, womit die Objekte linksbündig, rechtsbündig oder zentriert positioniert werden können.ypos: Die y-Position der Objekte auf dem Spielfeld (unter Berücksichtigung vom oberen Abstand vom Spielfeldrand bzw. Bereichsrand). Die Angabe muss als numerischer Wert in Pixel oder als Prozentwert (als Zahl mit anschließendem %) erfolgen oder einer der folgenden Werte sein: top, bottomoder middle, womit die Objekte oben, unten oder mittig positioniert werden können.percentsize: Die prozentuelle Größe in welcher die Bilder der Objekte dargestellt werden. Die Angabe muss als numerischer Wert erfolgen (ohne anschließendem %) oder einer der folgenden Werte sein: scale, scale_x oder scale_y. Bei der Prozentangabe bedeutet der Wert 100 die Normalgröße. Bei den Skalierungsvarianten werden die Objekte so skaliert (unter Beibehaltung des Seitenverhältnisses), dass sie das Spielfeld bzw. den Bereich horizontal (bei scale_x) oder vertikal (bei scale_y) ausfüllen. Bei scale wird so skaliert, dass die Objekte das Spielfeld bzw. den Bereich soweit wie möglich ausfüllen ohne darüber hinaus zu ragen.angle: Der Grad der Drehung mit welchem die Objekte dargestellt werden sollen. Die Angabe muss als numerischer Wert erfolgen. Standard ist 0.area: Der Name des Bereichs, in welchem die Objekte dargestellt werden sollen. Wenn ein Bereich angegeben ist, dann beziehen sich die Positionsangaben auf den Bereich - ansonsten auf das Spielfeld.xspacing: Der horizontale Versatz der einzelnen Objekte. Die Angabe muss als numerischer Wert in Pixel erfolgen.yspacing: Der vertikale Versatz der einzelnen Objekte. Die Angabe muss als numerischer Wert in Pixel erfolgen.orientation: Die Richtung in welcher die Objekte dargestellt werden sollen. Folgende Werte sind gültig: ltr_down (von links nach rechts und dann nach unten), ltr_up (von links nach rechts und dann nach oben), down_ltr (von oben nach unten und nach rechts), up_ltr (von unten nach oben und dann nach rechts), rtl_down (von rechts nach links und dann nach unten), rtl_up (von rechts nach links und dann nach oben), down_rtl (von oben nach unten und dann nach links) oder up_rtl (von unten nach oben und dann nach links).wrapthreshold: Bestimmt nach wie vielen Objekte umgebrochen werden soll. Dieser Wert ist nur relevant, wenn orientation angegeben wurde.Eine Spielerinformation (playerinfo) unterstützt folgende Attribute:
type: Der Typ der Information. Folgende Werte sind erlaubt:name: Der name des Spielers.game_score: Die Punkte des Spielers im aktuellen Spiel.round_score: Die Punkte des Spielers in der aktuellen Runde.turn_score: Die Punkte des Spielers vom aktuellen Durchgang.playerindex: Der Index des Spielers, für welchen die Information angezeigt werden soll. Die Angabe muss als numerischer Wert erfolgen. Der erste Spieler hat den Index 0.xpos: Die x-Position der Information auf dem Spielfeld (unter Berücksichtigung vom linken Abstand vom Spielfeldrand bzw. Bereichsrand). Die Angabe muss als numerischer Wert in Pixel oder als Prozentwert (als Zahl mit anschließendem %) erfolgen oder einer der folgenden Werte sein: left, right oder center, womit die Information linksbündig, rechtsbündig oder zentriert positioniert werden können.ypos: Die y-Position der Information auf dem Spielfeld (unter Berücksichtigung vom oberen Abstand vom Spielfeldrand bzw. Bereichsrand). Die Angabe muss als numerischer Wert in Pixel oder als Prozentwert (als Zahl mit anschließendem %) erfolgen oder einer der folgenden Werte sein: top, bottomoder middle, womit die Information oben, unten oder mittig positioniert werden können.fontsize: Die Schriftgröße, in welcher die Information dargestellt werden soll. Die Angabe muss als numerischer Wert in Punkten oder als Prozentwert (als Zahl mit anschließendem %) erfolgen oder einer der folgenden Werte sein: scale, scale_x oder scale_y. Bei der Prozentangabe bezieht sich der Wert auf die Höhe des Bereichs bzw. auf das Spielfeld. Bei den Skalierungsvarianten wird die Information so skaliert, dass sie das Spielfeld bzw. den Bereich horizontal (bei scale_x) oder vertikal (bei scale_y) ausfüllen. Bei scale wird so skaliert, dass die Information das Spielfeld bzw. den Bereich soweit wie möglich ausfüllt ohne darüber hinaus zu ragen.color: Die Farbe, in welcher die Information dargestellt werden soll. Die Angabe muss im Format RRGGBB erfolgen, wobei RR für den Rotanteil, GG für den Grünanteil und BB für den Blauanteil steht. Die Anteile müssen in hexadezimalen Werten angegeben werden.angle: Der Grad der Drehung mit welchem die Information dargestellt werden sollen. Die Angabe muss als numerischer Wert erfolgen. Standard ist 0. Unter Android ist dieses Attribut nicht verfügbar!area: Der Name des Bereichs, in welchem die Information dargestellt werden soll. Wenn ein Bereich angegeben ist, dann beziehen sich die Positions- und Größenangaben auf den Bereich - ansonsten auf das Spielfeld.Klänge können ähnlich wie Spielmaterialien konfiguriert werden. Es gibt einzelne Klänge und Sets von Klängen. Klänge und Sets von Klängen können auch zu Zusammenstellungen zusammengefügt werden.
Wie bei Spielmaterialien können auch Klänge versteckt werden. Versteckte Klänge werden im Dialog zum Ändern der Zusammenstellungen der Klänge nicht angezeigt. Das Schlüsselwort hierzu ist hidden, das entweder auf false oder true gesetzt wird. Der Entwickler kann sowohl auf die versteckten als auch die sichtbaren Klänge zugreifen. Versteckte Klänge können aber nie aktiv sein, dies betrifft vor allem Methoden von GameConfig: so werden z.B. versteckte Klänge bei getSounds() zurückgegeben, bei getActiveSound() kann es sich hingegen nie um einen versteckten Klang handeln.
Hinweis für Android Applications
In Android ist es möglich, dass einzelne Klänge, Sets von Klängen oder Zusammenstellungen erst über In-App-Purchases gekauft werden müssen. Dazu muss beim entsprechenden Klang, Set von Klängen oder Zusammenstellung das Attribut productid angegeben werden. Der Wert muss der ID des Produkts in der Google Play Console entsprechen. Mehrere Klänge, Sets von Klängen oder Zusammenstellungen können die gleiche Produkt-ID haben.
Es wird dann in der Auswahlliste neben dem Klang ein 🔒-Symbol angezeigt (Text-Ressource unpurchased_marker). Wenn ein solches Element ausgewählt wird, dann wird der Kaufprozess angestoßen. Wird der Kauf erfolgreich abgeschlossen, dann wird das Symbol entfernt und der Klang kann verwendet werden.
Solange ein nicht gekauftes Element ausgewählt ist, kann kein Spiel gestartet werden.
Beispiel:
<sounds extension="wav" path="/sounds">
<sound type="play_card" name="play_card_standard"/>
<sound type="play_card" name="play_card_alternative" file="/assets/playcard.wav" productid="alternativ_sounds"/>
<soundset type="roll_dice" name="roll_dice_standard">
<sound sequencestart="1" sequenceend="10"/>
</soundset>
<soundset type="roll_dice" name="roll_dice_alternative" productid="alternativ_sounds">
<sound sequencestart="1" sequenceend="5"/>
<sound sequence="6" file="/assets/rolldice.wav"/>
</soundset>
</sounds>
Es können sowohl einzelne Klänge als auch Sets definiert werden. Zur Identifizierung wird ein Typ definiert (type). Alle Klänge desselben Typs gehören zusammen und sind Alternativen im Dialog für die Zusammenstellung der Klänge. Pro Typ gibt es in diesem Dialog dann eine Combobox. Für die Typen müssen auch Meldungen in der Datei für die Meldungen definiert werden. Werden einzelne Klänge definiert, so beinhalten diese jeweils nur einen Klang. Werden Sets definiert, so beinhalten diese mehrere Klänge. Das kann z.B. dafür genutzt werden, dass beim Würfeln unterschiedliche Würfelklänge wiedergegeben werden.
<sounds extension="wav" path="/sounds">
<sound type="play_card" name="play_card_standard"/>
<sound type="play_card" name="play_card_alternative" file="/assets/playcard.wav"/>
<soundset type="roll_dice" name="roll_dice_standard">
<sound sequencestart="1" sequenceend="10"/>
</soundset>
<soundset type="roll_dice" name="roll_dice_alternative">
<sound sequencestart="1" sequenceend="5"/>
<sound sequence="6" file="/assets/rolldice.wav"/>
</soundset>
</sounds>
extension: Dateierweiterung für die Klangdateien.path: Verzeichnis, in dem die Klangdateien gesucht werden.sound: Definiert einen Klang. Es wird ein Typ (type) und ein Name (name) benötigt. Der Name muss eindeutig sein und wenn der Klang nicht versteckt ist, muss eine Meldung für den Namen definiert sein. Optional kann das Attribut file gesetzt werden, ansonsten wird die Datei <path>/<name>.<extension> verwendet.soundset: Ein Set benötigt einen Typ (type) und einen eindeutigen Namen (name) und wenn das Set nicht versteckt ist, muss eine Meldung für den Namen definiert sein. Für einen einzelnen Klang wird das Attribut sequence definiert, für einen Sequenzbereich gibt es die Attribute sequencestart und sequenceend (alle Angaben müssen numerisch sein). Es kann auch die Datei mittels file definiert werden, ansonsten werden die Dateien im folgenden Format gesucht: <path>/<name>/<type>-<sequence>.<extension> (sequence steht hierbei auch für einen einzelnen Wert des Sequenzbereichs). Wenn ein Dateiname bei einem Sequenzbereich definiert ist, bekommen alle Elemente den gleichen Klang.Verschiedene Klänge und Sets von Klängen können zu Zusammenstellungen zusammengefasst werden. Solche Zusammenstellungen machen nur Sinn, wenn der Dialog für das Ändern der Zusammenstellungen erreichbar ist (Menübefehl settings.sounds).
<soundarrangements complete="false">
<soundarrangement name="arrangement_standard">
<sound type="play_card" value="play_card_standard"/>
<soundset type="roll_dice" value="roll_dice_standard"/>
</soundarrangement>
<soundarrangement name="arrangement_alternative">
<sound type="play_card" value="play_card_alternative"/>
<soundset type="roll_dice" value="roll_dice_alternative"/>
</soundarrangement>
</arrangements>
complete: (Optional) Bestimmt, ob nur die definierten Zusammenstellungen möglich sind, oder ob der Benutzer die Zusammenstellungen auch beliebig abändern kann. Falls complete auf true gesetzt ist, können die Zusammenstellungen nicht abgeändert werden. In diesem Fall sollten also die einzelnen Zusammenstellungen komplett sein, also alle vorkommenden Spielmaterialien beachten. Standardmäßig ist das Abändern möglich.soundarrangement: Jede Zusammenstellung wird durch einen eindeutigen Namen (name) identifiziert. Für diesen Namen sollte auch eine Meldung definiert sein.sound: Für jeden Klang kann ein Eintrag gemacht werden, wobei das Attribut type den Typ bestimmt und das Attribut value den Namen des zu der Zusammenstellung gehöhrenden Klangs.soundset: Für Sets können Einträge analog wie für einzelne Klänge gemacht werden.
