7 Struktura XML dokumentů
Struktura všech XML dokumentů je pevná, avšak některé části nejsou povinné. Pokud má být obsahem tagu číslo, je upřesněno, kterých hodnot může nabývat - (N) značí celá kladná čísla a tedy typ int, (R) značí reálná čísla a tedy typ double, popřípadě je dáno rozmezí hodnot. Záporné hodnoty ve většině případů nejsou povoleny, pokud však ano, je to u popisu daného tagu zmíněno.
7.1 Config.xml
Základním konfiguračním souborem je soubor config.xml. Obsahuje výchozí nastavení některých proměnných v aplikaci a dále obsahuje jednotlivé profily uživatelů.
Default_K8pack udává aktuálně použitý balíček zdrojů. Default_language udává index jazyka, který bude použit, pokud není vybrán profil - ten také mimo jiné také určuje, která jazyková varianta se použije. Dále jsou výchozí nastavení hlasitosti hudby, rychlosti animací, default_announce rovná 1 říká, že výchozí nastavení je takové, že server oznamuje o svých hrách. Každý profil obsahuje jméno, pod kterým bude uživatel v aplikaci vystupovat, nastavení rychlosti a hlasitosti pro daný profil a zda hra ním vytvořená má být oznamována. Nejmenší index profilu je 1 a jejich počet není (teoreticky) omezen.
<K8>
<default_K8pack>./</default_K8pack>
<default_language>1</default_language>
<last_profile>1</last_profile>
<default_speed>3</default_speed>
<default_sfx_volume>0</default_sfx_volume>
<default_music_volume>0</default_music_volume>
<default_fullscreen>0</default_fullscreen>
<default_resolution>0</default_resolution>
<default_announce>1</default_announce>
<profiles>
<profile id="i3">
<name>Test2</name>
<language>1</language>
<announce>1</announce>
<fullscreen>1</fullscreen>
<music_volume>0</music_volume>
<speed>3</speed>
<sfx_volume>0</sfx_volume>
</profile>
...
</profiles>
</K8>
7.2 Files.xml
Druhým důležitým konfiguračním souborem je files.xml. Zde jsou jména indexových souborů pro jednotlivé RM bez přípony. Jeho struktura je pevná a musí obsahovat odkazy na všechny indexové soubory - indexový soubor pro jednotky (v současnosti) units.xml, pro budovy buildings.xml, pro zvuky sounds.xml, pro symboly symbols.xml, pro bonusy bonuses.xml, pro modely models.xml, pro rasterové obrázky rasters.xml a pro další menší XML soubory others.xml.
<K8>
<unit>units</unit>
<lang>languages</lang>
<raster>rasters</raster>
<sound>sounds</sound>
<symbol>symbols</symbol>
<model>models</model>
<other>others</other>
<building>buildings</building>
<bonus>bonuses</bonus>
</K8>
Jednotlivé indexové soubory obsahují záznamy o všech použitelných datech daného typu. Atribut id u "hlavního" tagu udává index daného objektu, který musí být jednoznačný v rámci daného souboru. Dále je zde odkaz na vlastní datový soubor (Castle.xml) a odkazy na zdroje využívané - 3D modely zobrazované ve hře construction_model a model na RMmodel, symbol (obrázek tlačítka budovy) na RMsymbol a name neboli jméno budovy na RMtxt. Další okazy objevující se v jiných souborech jsou pak odkaz na raster rasterid a určení typu type. Všechny indexy, ve všech indexových souborech, jsou typu (N).
<building id="i1">
<construction_model>66</construction_model>
<file>Castle</file>
<model>56</model>
<name>104</name>
<symbol>41</symbol>
</building>
...
Závislosti mezi RM jsou zobrazeny na následujícím obrázku, vždy na šipce je jméno tagu, kterým je tato závislost vytvořena. Jediný rozdíl je u RMmodel, který se odkazuje na RMraster pomocí jména souboru obrázku uloženého přímo v datech modelu. Popis fungování a významu jednotlivých RM a jejich metod je v kapitole
správa zdrojů.

Diagram 7.1: Závislosti mezi jednotlivými Resource Managery.
Jedná se jen o závislosti, nutné k tomu, aby bylo možné s daným objektem pracovat (např. zobrazit) - tj. závislosti, které jsou určené (až na RMmodel) v indexových souborech. Pokud by se zkoumaly všechny závislosti, byl by jejich počet větší - např. v XML souboru budovy se vyskytuje odkaz na jednotky, které lze v dané budově vyrábět. Tato závislost však nebrání zobrazení budovy samotné a ve hře pak data k jednotce budou k dispozici, jelikož všechny jednotky jsou načteny před spuštěním hry.
7.3 Jednotky
Soubor jednotky obsahuje všechny hodnoty a koeficienty, které dané jednotky mají. Jednotky jsou umístěny v adresáři xml/units. Některé z těchto hodnot se v průběhu hry mění - upravují se na základě různých okolností - počet životů se snižuje po boji, počet bodů pohybu se snižuje po jakékoliv provedené akci apod. Tyto hodnoty lze tedy považovat za výchozí "nastavení" daného typu jednotek. U každého tagu je vždy na konci popisu určen typ hodnoty - celé kladné číslo (N), nebo reálné kladné číslo (R).
- <type> udává typ jednotky - 0 značí pěchotu, 1 jízdu, 2 stroj, 3 jednotlivec, 4 netvor a 5 létající jednotka. (N)
- <terrain> obsahuje tagy všech typů terénů a tyto pak obsahují buď 0, pokud daná jednotka na tento terén nesmí a nebo koeficient zpomalení (pokud je hodnota mezi 0 a 1) nebo zrychlení (pokud je hodnota větší než 1). (R)
- <elevation> obsahuje tagy všech výškových stupňů a jejich obsahem je koeficient zrychlení resp. zpomalení při pohybu v dané nadmořské výšce. (R)
<type>0</type>
<movement_points>3</movement_points>
<terrain>
<plain>1</plain>
<forest>0</forest>
<deepforest>0</deepforest>
<rocks>1</rocks>
<swamp>2</swamp>
<river>0</river>
<shallow>2</shallow>
<sea>0</sea>
<town>1</town>
</terrain>
<elevation>
<level_0>1</level_0>
<level_1>1</level_1>
<level_2>1</level_2>
<level_3>1</level_3>
<level_4>1</level_4>
</elevation>
- <downhill> je koeficient upravující cenu pohybu při pohybu z kopce. (R)
- <uphill> je koeficient upravující cenu pohybu při pohybu do kopce. (R)
- <meninrow> udává kolik mužů stojí v řadě ve formaci, kterou jednotka udržuje. (N)
- <attack> je útočné číslo jednotky. (N)
- <defense> je obranné číslo jednotka. (N)
- <fight> udává možnosti kombinace boje a pohybu. 0 znamená libovolné pořadí (i opakované) akcí pohybu a útoku (do vyčerpání bodů pohybu), 1 jednotka se může libovolně pohybovat a pak zaútočit (útokem ztrácí zbývající BP), 2 pokud se jednotka hne, nemůže už útočit, 3 jednotka se může buď jen pohybovat nebo jen útočit během jednoho kola. (N)
- <counterattack> síla protiútoku. Pokud se jednotka nemůže bránit, obsahuje 0. (N)
- <fight_type> způsob boje - 0 znamená boj tváří v tvář, 1 útok výbušninami, při kterých jednotka i umírá, 2 střelba z ručních zbraní (např. lučištníci), 3 střelba přímo (střelný prach), 3 balistická střelba (katapult).
<downhill>1</downhill>
<uphill>2</uphill>
<meninrow>5</meninrow>
<attack>10</attack>
<defense>10</defense>
<fight>2</fight>
<counterattack>10</counterattack>
<fight_type>2</fight_type>
Následují 2 koeficienty upravující sílu útoku. Jeden je pro útočníka a jeden pro obránce. Každý tag opět obsahuje subtag pro každý typ terénu - a jejich obsahem je vlastní koeficient. <attack_bonus_against> udává bonus na terén, na který jednotka útočí. <defense_bonus_against> pak upravuje obranu obránci vzhledem k terénu, odkud je na něj veden útok. Příkladem, kde se dané hodnoty využijí, je např. útok lučištníků na jednotku v lese. (R)
- <attack_against> pro každý typ jednotek obsahuje koeficient k útoku mezi typy jednotek. (R)
<attack_against>
<infantry>0</infantry>
<cavarly>0</cavarly>
<vehicle>0</vehicle>
<beast>0</beast>
<individual>0</individual>
<flying>0</flying>
</attack_against>
- <attack_buildings> koeficient útoku na budovu. (R)
- <range> udává dosah útoku (počet hexů). Pokud je nastaven na 0, jednotka nemůže útočit. (N)
- <hit> udává pravděpodobnost zásahu (pro stroje) a nabývá hodnot mezi 0 a 1. (R)
- <occurrence> 1 znamená možnost nákupu (výskyt) jednotky po celé mapě, 0 pouze v místech, kde je tak explicitně řečeno (N).
- <cost> nákupní cena jednotky (N)
- <pay> žold jednotky za jedno kolo (N)
- <eyesight> počet hexů udávající, kam až jednotka "vidí" (N)
- <build_building> zda jednotka může stavět budovu - hodnota 1. Pokud nemůže 0. (N)
- <bonuses> seznam identifikací bonusů, které se nechají v budově koupit (N)
<attack_buildings>0</attack_buildings>
<range>4</range>
<hit>0</hit>
<occurrence>1</occurrence>
<cost>0</cost>
<pay>0</pay>
<max_lives>15</max_lives>
<cure_cost>0</cure_cost>
<eyesight>1</eyesight>
<build_building>0</build_building>
<bonuses>
<bonus id="3">1</bonus>
<bonus id="4">1</bonus>
</bonuses>
7.4 Bonusy
Bonusy, možnost, jak zvýšit některou vlastnost jednotky nad její výchozí hodnotu během hry jsou uloženy v adresáři xml/bonuses a obsahují
- <property> vlastnost, kterou bonus zlepšuje - 0 pro zvýšení útoku, 1 zvýšení obrany, 2 zvýšení dohledu, 3 zvýšení počtu životů, 4 zvýšení počtu bodů pohybu, 5 zvýšení dostřelu (pouze u střeleckých jednotek)
- <bonus> o kolik se daná vlastnost zvýší (N)
- <cost> nákupní cena bonusu (N)
<K8>
<property>1</property>
<bonus>1</bonus>
<cost>0</cost>
</K8>
7.5 Budovy
Informace o budovách, podobně jako informace o jednotkách, jsou základní a obecné - pro každý typ budov existuje jeden soubor uložen v adresáři xml/buildings. Vlastní aktuální hodnoty, které se během hry mění, jsou uloženy přímo v souboru mapy.
- <hit_probability> pravděpodobnost zásahu strojem (R)
- <lives> maximální počet životů (N)
- <base_cost> cena za postavení budovy (N)
- <repair_cost> cena za opravení jednoho života budovy (N)
- <construction_duration> doba stavby (N)
- <structure_type> typ budovy - budova může být otevřená (například most) - hodnota 0 nebo uzavřená - hodnota 1. (N)
- <position> pozice, ze které se začne budova stavět. 0 znamená, že se začne stavět na stejném hexu, 1 na vedlejším (např. pro most).
<hit_probability>0.550000</hit_probability>
<lives>114</lives>
<base_cost>300</base_cost>
<repair_cost>1</repair_cost>
<construction_duration>3</construction_duration>
<structure_type>0</structure_type>
<position>0</position>
- <counterattack> síla protiútoku (N)
- <defense_bonus> bonus k obraně jednotky uvnitř (N)
- <eyesight> dosah vidění budovy (N)
- <terrain> pro každý typ terénu 0 znamená, že se zde budova postavit nemůže, 1 znamená může (N)
- <recruitments> seznam typů jednotek, které se nechají v budově vyrábět. Index každého typu je uveden v subtagu <recruitment>, které jsou očíslovány parametrem id od 1 dále.
- <bonuses> seznam bonusů, které lze v budově koupit. Pro každý index bonusu, které lze zde koupit, je zde obsažen jeden řádek bonus s id indexu bonusu a hodnotou 1.
- <orientation_count> počet orientací (otočení budov). Typická hodnota je 6, most jich má 12.
<counterattack>0</counterattack>
<defense_bonus>0</defense_bonus>
<eyesight>1</eyesight>
<terrain>
<plain>1</plain>
<forest>0</forest>
<deepforest>0</deepforest>
<rocks>0</rocks>
<swamp>0</swamp>
<river>0</river>
<shallow>0</shallow>
<sea>0</sea>
<town>0</town>
</terrain>
<recruitments>
<recruitment id="i1">1</recruitment>
</recruitments>
<bonuses>
<bonus id="1">1</bonus>
<bonus id="2">2</bonus>
<bonus id="3">4</bonus>
</bonuses>
<orientation_count>6</orientation_count>
7.6 Terény
Popisy terénů, které jsou uloženy v adresáři xml/terrains a jejichž pozice je určena indexovým souborem others.xml, mají následující strukturu
- <healing_reduction> určuje, zda se jde na daném terénu léčit (N)
- <hit_probability_reduction> snížení pravděpodobnosti zásahu (R)
- <visibility_reduction> zda terén brání rozhledu - hodnota je 0, nebo nikoli, pak je hodnota 1. (N)
<?xml version="1.0" encoding="UTF-8"?>
<K8>
<healing_reduction>0.5</healing_reduction>
<hit_probability_reduction>0.8</hit_probability_reduction>
<visibility_reduction>1</visibility_reduction>
</K8>
7.7 Symboly
Soubor symbolů obsahují informace o pozicích jednotlivých symbolů, v obrázku, který je určen v indexovém souboru všech sad symbolů a jsou uloženy v adresáři xml/symbols. Ty ve hře odpovídají především obrázkovým tlačítkům.
- <x> x-ová souřadnice levého horního rohu symbolu v pixelech (N)
- <x> y-ová souřadnice levého horního rohu symbolu v pixelech (N)
- <width> šířka symbolu (N)
- <height> výška symbolu (N)
...
<symbol id="i11">
<x>42</x>
<y>1</y>
<width>40</width>
<height>37</height>
</symbol>
...
7.8 TCL skripty
Strukturovanější jsou záznamy o TCL skriptech, které jsou také uloženy v XML souborech v adresáři xml/scripts. Z důvodu, že se v nich často vyskytují znaky, které se samostatně vyskytovat nemohou (např. porovnání velikosti "<" ), je nutné využívat buď entit nebo uzavřít tělo skriptu do konstrukce <![CDATA[]]>. Vše, co je uzavřeno do těchto "závorek", se považuje a text, který se nekontroluje parserem.
- <head> slouží k určení vstupních parametrů. Každý vstupní parametr tvoří subtag <param id="i1"> s očíslovaným id od 1 dále. Parametr je dále určen názvem v tagu <name> a typem v tagu <type>. Typů je rozeznáváno 9 - int, double, string, unit, building, hex a tři typy list.
- <body> obsahuje vlastní tělo skriptu
- <tail> specifikuje výstupní parametry. Jeho struktura je shodná s tagem <head>
<K8>
<head>
<param id="i1">
<name>x</name>
<type>int</type>
</param>
<param id="i2">
<name>y</name>
<type>int</type>
</param>
</head>
<body>
set z [expr $x + $y];
</body>
<tail>
<result id="i1">
<name>z</name>
<type>int</type>
</result>
</tail>
</K8>
7.9 Textové řetězce
Naopak struktura souborů s řetězci v jednom jazyce je jednodušší. Jedná se pouze o soubor tagů <text> s různými id, kdy každý záznam obsahuje jedno slovo (například pro popis tlačítek) či větu (například pro popis události ve hře). Platí, že v každém jazykovém souboru je pod stejným id veden obsahově stejný řetězec.
- <text> jeden řetězec (resp. odstavec) v daném jazyce
...
<text id="i427">Nová hra</text>
<text id="i430">Jméno profilu</text>
...
7.10 Mapy
Mapy jsou ze všech dat ukládaných v XML souborech nejstrukturovanější. Z pohledu uživatele jsou mapy rozděleny do dvou typů - nové a uložené a podle toho uložené v adrsáři xml/maps a savegame. Z pohledu aplikace tyto dvě skupiny splývají a i jejich struktura je shodná.
Na začátku souboru s mapou je hlavička. Hlavička obsahuje souhrnné informace o mapě, které jsou potřeba již v přehledu map (např. když si uživatel vybírá, kterou mapu chce hrát).
- <sizex> šířka mapy v hexech (N)
- <sizey> výška mapy v hexech (N)
- <name> jméno mapy - zde není odkaz do RMtxt, avšak je tu přímo vlastní text. To zaručuje přenositelnost map.
- <description> popis mapy, nastínění situace, historie apod. I zde platí, že je zde přímo vlastní text.
- <roles> pro všechny role ve hře obsahuje subtag <role> s id mezi 1 a 8 včetně. Hráč si před hrou vybírá, kterou roli na sebe vezme a kterou říši bude zastávat. Každá role dále obsahuje informaci o jménu říše a aktuálním počtu peněz, které má k dispozici, dále vztahy s ostatními hráči a statistiky říše.
<header>
<sizex>10</sizex>
<sizey>30</sizey>
<name>Name</name>
<description>Desc</description>
<roles>
<role id="i1">
<name>Role1</name>
<money>1000</money>
<state>0</state>
<statistics>
<unitsKilled>0</unitsKilled>
<unitsLost>0</unitsLost>
<unitsCreated>0</unitsCreated>
<buildingsBuilt>1</buildingsBuilt>
<buildingsCaptured>0</buildingsCaptured>
<buildingsLost>0</buildingsLost>
<buildingsDestroyed>0</buildingsDestroyed>
<townsCaptured>0</townsCaptured>
<townsLost>0</townsLost>
<kingdomsCaptured>0</kingdomsCaptured>
<kingdomsLost>0</kingdomsLost>
<moneyGained>435</moneyGained>
</statistics>
<relations>
<role id="2">
<state>2</state>
<offered>2</offered>
<delivered>1</delivered>
<belief>6250</belief>
<guessBelief>6250</guessBelief>
</role>
</relations>
</role>
...
</roles>
</header>
Strategický plán umělé inteligence obsahuje pro každou roli, kterou UI ovládá jeden tag, s kódovanými informacemi.
<ai>
<plan id="2">688|458|382|@3|9|1|6|12|1|4|9|1|@0$-1$5$-1$0$|1|274|194|-1|0|@@@</plan>
</ai>
Následují informace, které se načtou, až po vybrání konkrétní mapy k načtení. První z nich je aktuální stav hry.
<currentState> místo kde je uložen aktuální stav. Obsahuje subtagy <onTurn>, určující, která role je na tahu a <weather> určující aktuální počasí (0 jasno, 1 déšť a 2 sněžení), <turn> udávající kolikátý tah právě probíhá a <duration> doba trvání počasí. Všechny hodnoty nabývají kladných čísel.
<currentState>
<turn>1</turn>
<duration>0</duration>
<onTurn>1</onTurn>
<weather>0</weather>
</currentState>
Dále v mapě jsou záznamy o královstvích.
- <kingdoms> obsahuje pro každé království subtag <kingdom>, který dále obsahuje id role, která ho vlastní (resp. 0, pokud toto království nikomu nepatří)
- <centerx> x-ová souřadnice středu království (N)
- <centery> y-ová souřadnice středu království (N)
<kingdoms>
<kingdom id="i1">
<role>2</role>
<centerx>3</centerx>
<centery>15</centery>
</kingdom>
...
</kingdoms>
Záznam o městech má podobnou strukturu.
- <cities> obsahuje pro každé město záznam <city>, které dále obsahuje
- <citysize> velikost města (N)
- <owner> id role, která město vlastní nebo 0
- pro každou část města tag <position> indexovaný od 1 do nejvýše 7 udává číslo hexu, který o města patří
<cities>
<city id="i1">
<citysize>4</citysize>
<owner>2</owner>
<position id="i1">124</position>
<position id="i2">134</position>
<position id="i3">144</position>
<position id="i4">135</position>
</city>
...
</cities>
Následuje vlastní tvar a povrch mapy.
- <map> uzavírá informace o povrchu mapy, obsahuje subtagy <hex>, indexované od 1 do počtu hexů na mapě. Ten dále obsahuje
- <occurrences> tento nepovinný atribut určuje seznam speciálních jednotek, které se na tomto hexu vyskytují
- <history> nepovinný atribut určující, kdy byl tento hex viděn a kterou budovu na tomto hexu daný hráč viděl
- <terrain> typ terénu na daném hexu. Pláně odpovídají 1, les 2, hvozd 3, skály 4, bažiny 5, řeka 6, moře 7, brod 8, město 9
- <elevation> nabývá hodnot 0 až 4 s tím, že vyšší číslo znamená vyšší terén. (N)
- <unit> nepovinný atribut určující, která jednotka na daném hexu stojí. (N)
- <building> nepovinný atribut určující, která budova na daném hexu stojí. (N)
- <kingdom> určuje do kterého království daný hex patří. (N)
<map>
<hex id="i1">
<occurrences>
<occurrence id="1">6</occurrence>
</occurrences>
<history>
<role id="2">
<round>14</round>
<building_type>0</building_type>
</role>
</history>
<terrain>1</terrain>
<elevation>1</elevation>
<unit>1</unit>
<building>1</building>
<kingdom>1</kingdom>
</hex>
</map>
Informace o jednotkách jsou umístěny v tagu units.
- Každá jednotka je uzavřena v tagu <unit> s jejím jednoznačným identifikátorem
- <type> typ (druh) jednotky
- <name> nepovinný atribut určující jméno jednotky
- <player> vlastník jednotky
- <movement> zbývající počet bodů pohybu.
- <lives> zbývající počet životů. (N)
- <level> úroveň jednotky. (N)
- <experiences> zkušenosti jednotky. (N)
- <bonuses> nepovinný atribut se seznamem bonusů vlastněných jednotkou
- <orientation> orientace jednotky - hodnoty 0 až 5
<units>
<unit id="i1">
<type>1</type>
<name>Jan Lucemburský</name>
<player>1</player>
<movement>0</movement>
<lives>1500</lives>
<wounds>
<man id="1">1</man>
</wounds>
<level>1</level>
<experiences>0</experiences>
<bonuses>
<bonus id="1">3</bonus>
</bonuses>
<orientation>0</orientation>
</unit>
...
</units>
Informace o jednotkách jsou umístěny v tagu buildings.
- Každá budova je pak uzavřena v tagu <building> s jejím jednoznačným identifikátorem
- <type> typ (druh) budovy.
- <name> nepovinný atribut určující jméno budovy.
- <lives> zbývající počet životů. (N)
- <player> vlastník jednotky.
- <constructionDuration> zbývající počet tahů k dostavení, značící, že budova je rozestavěná. (N)
- <orientation> orientace budovy - hodnoty 0 až 5 (pro most až 11)
<buildings>
<building id="i1">
<type>4</type>
<name>Bastille</name>
<lives>1500</lives>
<player>2</player>
<constructionDuration>2</constructionDuration>
<orientation>0</orientation>
</building>
...
</buildings>
7.11 Modifikování XML souborů
Všechna data jednotek, budov, map apod. jsou uloženy v otevřeném XML formátu. Tudíž jejich ruční modifikace je jednoduchá. Při případné modifikaci je však třeba dbát na správnost vložených/změněných dat. Případný problém pak může vést od poškození uložené mapy, což zabrání její hraní až po zabránění samotné aplikaci v běhu, při poškození důležitých dat. Také je vhodné poznamenat, že veškeré výpočty při hře jsou prováděny na straně serveru a tudíž modifikace např. vlastností jednotek u klienta nepovede k jejich vlastní změně během síťové hry.