|This article contains technical details about Naev.|
Every mission available to the player in NAEV is indexed in an XML file called mission.xml , which can be found within the naev/dat/ directory. This page documents the tags used to describe NAEV missions in XML. For examples of mission XML used by NAEV:Sea Of Darkness, look at the source of naev/dat/mission.xml. You can find general information about missions at the MissionDevelopement page.
- 1 The form of mission.xml
The form of mission.xml
Like any XML document, mission.xml contains exactly one root element. In this case, the <Missions> tag and it's corresponding </Missions> closing tag begin and end the mission.xml document. The root tag contains multiple <mission> tags, which define individual missions.
A Sample Mission Tag
The following XML snippet demonstrates all the tags that can make up the XML portion of a NAEV mission:
<mission name="Example 2"> <lua>example2</lua> <flags> <unique /> </flags> <avail> <priority>5</priority> <cond>var.peek(boolean_condition) == true</cond> <done>Example 1</done> <chance>220</chance> <location>Computer</location> <faction>Some Faction</faction> <planet>Some Planet</planet> </avail> </mission>
Tag by Tag Explanation of the Mission XML
The <mission> xml tag and its children determine some basic attributes of the mission. Read on for explanations about what they do. Only the <unique /> tag is self-closing. All other tags must be paired: one opening tag such as <chance> with a similar closing tag such as </chance>. The content of the tag belongs between the opening and closing tag.
The <mission> tag defines an individual mission. Each mission tag has a name attribute, declared in the form name="sample_name" before the concluding > of the opening tag. The <mission> tag must contain a <lua> tag and an <avail> tag, and can also contain an optional <flags> tag.
The <lua> tag can contain text, but not another XML tag. It links the mission XML to a corresponding Lua file. To find the file, the NAEV engine looks within the directory /naev/dat/missions/ for a file with the same name as the content of the tag. In the example snippet above, the tag <lua>example2</lua> points to the file naev/dat/missions/example2.lua This tag can also point to files in subdirectories. <lua>neutral/example2</lua> points to the file naev/dat/missions/neutral/example2.lua Unless the <lua> tag names a valid file, the mission will not appear in the game.
The <flags> tag is optional. If it appears in a mission's XML, the tag can contain a <unique> tag, but no other content.
At the moment, there is only one valid flag tag. The <unique /> tag has no content. If it appears in a <flags> tag, it ensures that the relevant mission will not appear again if that mission exits with the Lua API function mission.finish( true). Missions can have multiple end points. If a mission exits with mission.finish( false) that mission may appear again, even if the <unique> flag is present in the mission XML.
The <avail> tag contains tags that determine the conditions under which a mission will appear. Although by itself it does nothing, this tag is required for a mission to appear in the game. The <avail> tag can contain only the following tags: <priority>, <cond>, <done>, <chance>, <location>, <faction>, and <planet>.
The <priority> tag is optional. If it appears it indicates how important the mission is. Lower priorities are more important. The default is 5.
The <cond> tag is optional. If it appears, it must be the child tag of a containing <avail> tag. The <cond> contains text which must be a boolean expression written in Lua. If the expression evaluates to true, and other availability conditions are satisfied, the mission appears in the game. The Lua expression in a <cond> tag is meant to use the NAEV Lua API to check, for instance, whether the player has a high enough combat rating, or is friendly with a certain faction. In the XML snippet above, the tag <cond>var.peek(boolean_condition) == true</cond> checks whether a mission variable has been set to true.
There can only be one <cond> tag per avail. If you have multiple conditions you need to put into a mission, use "and" to connect the two statements.
The <done> tag is optional. If it appears it must be the child of a containing <avail> tag. The <done> tag contains text which must be the name attribute of another mission. If the tag content names a mission the player has successfully completed (a mission that has exited with misn.finish( true)), then the present mission will be available, assuming other conditions are met. In the XML snippet above, the tag <done>Example 1</done> means that the mission "Example 2" will only be available after the mission with the name "Example 1" has been successfully completed.
The <chance> tag is a required child of an <avail> tag. It can contain only a number larger than or equal to 0. The last two digits of the number in a <chance> tag determine the likelihood a mission will appear when a player lands on a planet. If the chance number is three digits long, the first digit determines how many times that probability is calculated on each landing. A number larger than 200 means the mission may appear more than once simultaneously. A number between 101 and 200 has an equivalent in the 1 to 100 range. The ambiguous case of #00 is treated as 100%, so for example 300 would be 3 missions always, while 299 would be 2 with 99% chance and 301 would be 3 with 1% chance. In the XML snippet above, the tag <chance>220</chance> means the "Example 2" mission can appear up to two times. Each appearance has a 20 percent probability.
The <location> tag determines where a mission will appear. This tag is a required child of an <avail> tag. The <location> tag can contain only one of the following texts:
Each option corresponds to a location where the mission can be found. Missions located in "Space" are tested each time the player enters the system.
In the XML snippet above, the tag <location>Computer</location> mean that the "Example 2" mission is offered from the Mission Computer.
The <faction> tag is an optional child of an <avail> tag. It limits the mission to appear in ports that belong to a specific faction. To be valid, this tag should contain text identical to the name attribute of a <faction> tag in the file naev/dat/faction.xml In the XML snippet above, the tag <faction>Some Faction</faction> means that the mission will appear only on planets belonging to the faction with the name "Some Faction" defined in naev/dat/faction.xml There can be multiple <faction> tags in each <avail> tag.
The <planet> tag is an optional child of an <avail> tag. It allows the mission to appear on specific planets. To be valid, this tag should contain text identical to the name attribute of a <asset> tag in the file naev/dat/asset.xml In the XML snippet above, the tag <planet>Some Planet</planet> means that the mission can appear on the planet with the name "Some Planet" defined in naev/dat/asset.xml There can be multiple <planet> tags in each <avail> tag.