Editing XML/Scenario

{{XMLs}}
[[Scenarios]] are special types of battles where the creator can modify the game from its regular style, and even add [[Lua]] scripting.

{{TOC limit|2}}

==Folders==
The scenario XMLs differ slightly based on the engine used. In [[Glest]] and [[MegaGlest]], the scenario XML is located in <tt>scenarios/'''[scenario]'''</tt> (where <tt>[scenario]</tt> is the name of your scenario). In GAE, it is placed in <tt>gae/scenarios/'''[category]'''/'''[scenario]'''</tt> (where <tt>[category]</tt> is a folder of any name to categorize scenarios and <tt>[scenario]</tt> is the name of the scenario). In both engines, the scenario folder must have the same name as the XML.

==XML==
{{XML_definition_header}}
<syntaxhighlight lang="xml">
<?xml version="1.0" standalone="yes" ?>
<scenario>
	<difficulty value="3"/>
	<players>
		<player control="human" faction="faction_name" team="1"/>
<!-- Start MG Only -->
		<player control="network" faction="faction_name" team="2"/>
		<player control="cpu" faction="faction_name" resource_multiplier="1.0" team="2"/>
<!-- End MG Only -->
	</players>
	<map value="map_name"/>
	<tileset value="tileset_name"/>
	<tech-tree value="techtree_name"/>
	<!-- Start GAE+MG Only -->
	<fog-of-war value="true"/>
	<!-- End GAE+MG Only -->
	<default-resources value="true"/>
	<default-units value="true"/>
	<default-victory-conditions value="true"/>
	<!-- Start GAE Only -->
	<loading-screen>
		<background-image path="loading-screen.png" />
	</loading-screen>
	<!-- End GAE Only -->
	<scripts><!-- Start MG Only -->	
		<global>
		
			<!-- Lua Code -->
		
		</global>
		<onSave>
		
			<!-- Lua Code -->
		
		</onSave>
		<onLoad>
		
			<!-- Lua Code -->
		
		</onLoad>
		<!-- End MG Only -->
		<startup>
		
			<!-- Lua Code -->
		
		</startup>
		<unitCreated>
		
			<!-- Lua Code -->
		
		</unitCreated>
		<resourceHarvested>
		
			<!-- Lua Code -->
		
		</resourceHarvested>
		<unitCreatedOfType type="unit_name">
		
			<!-- Lua Code -->
		
		</unitCreatedOfType>
		<unitDied>
		
			<!-- Lua Code -->
		
		</unitDied>
		<!-- Start GAE Only -->
		<timer name="name">

			<!-- Lua Code -->

		</timer>
		<!-- End GAE Only -->
	</scripts>
</scenario>
</syntaxhighlight>

==Documentation==
===difficulty===
This is the displayed difficulty, as a number from 0-5. It does not affect the scenario in any way, and is only used to display what YOU think the difficulty should be classified as. The default english difficulties are:
:0 = Very Easy
:1= Easy
:2= Medium
:3= Hard
:4= Very Hard
:5= Insane

===players===
This is a list of the players in this game, where each player gets their own <tt>&lt;player /&gt;</tt> tag. Attributes are control, which is either <tt>human</tt>, <tt>cpu</tt>, or <tt>cpu-ultra</tt>, though [[GAE]] and [[MegaGlest]] add <tt>cpu-easy</tt> and <tt>cpu-mega</tt> as well. [[MegaGlest]] also adds the option of a <tt>network</tt> player. This asserts who controls that player, and one must be human and one must be some brand of cpu.
In [[MegaGlest]] you can also edit the resource multiplier for the cpu.

The faction is the name of the faction (must all be in the same techtree), and the team is the team number for the purpose of placing players on the same or different teams (players with the same number are allies, while different numbers are enemies).

===map===
The name of the map to use. It should exist in the player's maps folder. GAE can also have the map inside the scenario's folder itself, to allow the map to be used for the scenario only, without appearing in the regular game menu.

===tileset===
The name of the tileset to use. Note that it must exist in the user's tileset folder.

===tech-tree===
The techtree to use for the scenario. The existing factions for each player must exist in it.

===fog-of-war===
An optional value. If <tt>true</tt>, [[fog of war]] and the [[shroud of darkness]] will be displayed as normal, if <tt>false</tt>, there will be no fog of war nor the shroud of darkness. Finally <tt>explored</tt> will remove the shroud of darkness, but keep the fog of war.

===default-resources===
If true, the [[faction XML]] will be used to define the starting resources. If false, they start with no resources and you must use Lua to specify the resources to give. Generally on for non-scripted scenarios.

===default-units===
If true, the faction XML will be used to define the starting units. If false, they start with no units and you must use Lua to specify the units to give. Generally on for non-scripted scenarios.

===default-victory-conditions===
If true, the game is won or lost by defeating all the opponents (or more specifically, all the opponent's units which have a be-built [[skill]]). If false, the game only ends when the Lua script tells it to. Generally on for non-scripted scenarios.

===loading-screen===
A GAE only function to allow an image to be used as the loading screen background. If not loading screen image is used, exclude the tag completely. Currently in GAE 0.4, only the first specified image will work, but in the future, it may be possible to use multiple images, with one chosen on random.

===scripts===
{{See|Lua}}
Lua code will go in children tags of scripts. The exact Lua code available depends on the [[engine]] used, but the XML tags are all the same. Lua code will be executed based on what tag it is in.

{| class="wikitable"
!XML tag
!Description
|-
|&lt;global&gt;
|Everything in this tag will be executed whenever the scenario will be starded.
|-
|&lt;onSave&gt;
|Everything in this tag will be executed when the scenario gets saved. Here you can store variables you when the savegame gets loaded.
|-
|&lt;onLoad&gt;
|Everything in this tag will be executed when the savegame of the scenario is startd. Here you can also restore saved variables.
|-
|&lt;startup&gt;
|Everything in this tag will be executed ''once'' at the start of the scenario.
|-
|&lt;unitCreated&gt;
|Everything in this tag will be executed each time any player creates a new unit.
|-
|&lt;resourceHarvested&gt;
|Everything in this tag will be executed whenever a resource is harvested.
|-
|&lt;unitCreatedOfType&nbsp;type="unit_name"&gt;
|Everything in this tag will be executed when a unit of the specified name is created by any player.
|-
|&lt;unitDied&gt;
|Everything in this tag will be executed every time a unit from any player dies.
|-
|&lt;timer&nbsp;name="name"&gt;
|GAE only; executes when a [[GAE/Lua|Lua timer]] of the specified name goes off.
|}

==See also==
*[[XMLs]]
*[[Scenarios]]
*[[Lua]]
[[Category:XMLs]]