Overview of XML Writing for Mission-X
Based on v1.20
This document is based on v1.20 syntax, but the basics of XML are important.
First Steps to write your own Mission File
In this thread I will cover few topics regarding Mission-X data file, in order to simplify and make it easier to understand and build your own mission/s file/s. For more in-depth detail you should read the Mission-X Designer Guide.
The topics that I'll cover here are:
- Mission-X file format.
- Basic XML Rules.
- Basic XML Mission writing ( just to get the idea ).
- Designing your new mission.
- Creating the skeleton for your mission.
In each topic I'll cover some aspects but I'm limited at time, space and (unfortunately) English vocabulary. So please be patient and write me any useful feedback and I'll try to guide/help/correct when I can.
Please note that this topic is in early stages of writing, so changes may appear every once in a while.
Mission-X file format - Explained
In order to make a program that is cross platform, you sometime have to compromise. My compromise was to not create a graphical interface for mission designer (very steep learning curve for the programmer) and most of the time you are dealing with "User Interface" instead of the "Plugin Features". Since I have some experience with Web/Java/Database programming and managing, I came to respect the simple HTML format and the readability of the XML files (if constructed that way). This led me to search for Cross Platform C/C++ library that will be simple to implement and low on memory footprint.
So what is so special about the XML format ?
Except of some technical standards, nothing much. The main benefit for designer, is that all he/she needs are a good ASCII editor that can help with XML syntax and some patient. No special commands/compilers/administrative restrictions/Monopoly Patents should hamper our work or need to be learned. I'm not saying there are no rules to pay attention, but you can count them on one hand... so I guess you understand how simple XML can be.
Basic XML Rules
The rules of XML writing are quite simple and resembles HTML in many ways.
Rule No. 1: "Every Opening Element must have a closing"
An element is a descriptive word that tells the plugin, here is a new topic/info it help us divide the XML document to subjects and make hierarchy of data.
Here is an example to an Element:
<MISSION ...>
....
<Obj3D ...... />
</MISSION>
We can see here two ways to write an Element:
The first is the <MISSION> element, its closing element has the same name and same case, but with a slash before the name and it is written further down the document. The slash is like "ending" of Element.
The second way to write an Element is to declare the Element and its ending at the same declaration: [code]<Obj3D ....... />[/code]
The first rule is the most important in XML writing. There are no shortcuts.
Rule No. 2: Not all characters are valid in XML document.
Now this is a generalization declaration, there are always workarounds, but you need to know this.
Characters/Symbols like ">", ">=", "&" and others may cause the plugin not to read correctly the mission file. This is why you should stick to the designer guide Appendix when writing you mission.
Rule No 3: Keep your code tidy and indent.
Now this is not an XML rule but it is relevant to any descriptive/programming file/language.
When your mission becomes longer and you are adding more and more features into each Objective, it is very easy to lose orientation of what you wrote. So keep your elements indented, write brief comments to describe key topics for later testing and fixing.
In most cases I write comments between Objectives. It includes ICAO if relevant, name of location to reach, or what need to be done. This is very helpful when I test the mission and need to fix issues.
So that's it, these are the main rules when writing XML mission files, and I believe they are simple and intuitive ( other rules are not really relevant in our case ).
Basic XML Writing
Now that we understand the basic rules of XML writing, we can try and understand the Logic and Construction of Mission-X mission file. This is only an overview to grasp the idea.
So XML allow us to define a set of "elements" that will define our "Descriptive Language" of the Mission. By "descriptive" I mean meaningful names to describe the mission and they are defined by the plugin writer ( snagar, as of this writing ).
What a basic mission files need to have:
A mission files needs the following elements to be able to read the file and display the mission correctly:
- File Header.
- Describing of the Mission.
- Objectives and at least one target in each objective.
- Closing Description.
To better understand this, lets examine part of a simple mission XML file.
The following example is a snippet from "xplaneuser" mission "Royal Flying Doctor Service (RFDS) to Kiwirrkurra" and it is based on Mission-X v1.20 format.
Please read the snippet from start to end, explanation will come after it.
<?xml version="1.0" encoding="iso-8859-1"?>
<MISSION version="120" name="RFDS-Kiwirrkurra_Mission_120">
<GlobalSettings>
<Time days="90" hours="19" min="50" sec="0" />
</GlobalSettings>
<Briefer id="0" lat="-17.22154" long="123.39852" elev="29.0" icao="YDBY" locationAdjust="0" >
<Desc>
<![CDATA[The Royal Flying Doctor Service (RFDS) ..... (... more text ... ) ]]>
</Desc>
</Briefer>
<OBJECTIVES>
<!-- fly to Kiwirrkurra and pick up woman in labour -->
<Objective id="1" icao="YKIC" >
<Targets>
<StaticTarget id="1" lat="-22.810489" long="127.742634" elev="1400" needToLand="1" tolerateDistance="2.0" tolerateElev="" icao="YKIC" />
</Targets>
<Desc>
<![CDATA[ ... Objective Description ... ]]>
</Desc>
<Feedbacks>
<Broadcast id="1" subTarget="1" numToBroadcast="1" distanceToBroadcast="2.0" ><![CDATA[ ... message to broadcast ... ]]></Broadcast>
</Feedbacks>
....
</Objective>
.....
.....
<!-- Finishing Words -->
<Objective id="99" icao="YDBY" >
<Targets>
<StaticTarget id="1" lat="-17.369392" long="123.663413" elev="29.0" needToLand="1" tolerateDistance="1" tolerateElev="0" icao="YDBY" />
</Targets>
<Desc>
<![CDATA[ ... Finishing Words ... ]]>
</Desc>
</Objective>
</OBJECTIVES>
</MISSION>
The first thing to notice is that the XML file is readable. We can understand, in most cases, what the designer meant, and what needs to be done by the simmer.
We can also distinguish between main element and sub element, for example:
"MISSION", "GlobalSettings", "OBJECTIVES" are few of the main elements in a mission file.
"Objective", "Targets", "Desc" etc... are example for sub elements.
Do not get confused, almost every main element can be a sub element of other element (topic), but Mission-X has and defined its own elements hierarchy, so all you need is to stick to the hierarchy of elements described in the "Designer Guide" or in one of the mission files, and you are good to go.
The other thing to notice, that elements can have "attributes". An attributes defines the element itself, for example:"Briefer" element has an "icao" attribute that holds the name of the starting airport location. The attributes are also defined by the Mission-X programmer.
When dividing the snippet to subjects, we can describe the groups of elements as:
- Header: "?xml", "MISSION ", "GlobalSettings", "Briefer"
- Body: "OBJECTIVES", "Objective" ( sub element )
The header contain settings information for the plugin, holds the main description of the mission, logic and 3D object information ( not described here ) etc...
The Body is where the main writing will take place. Defining an Objective, its location point, its success rules and scenario info (weather and others ) are the designer way to express and deliver the mission intentions and spirit.
There are many more options/elements to explore and learn, but the designer guide is the right place to start with. gl
Designing your new mission
Before starting to write your first mission data file you firstly need to gather information regarding the mission you want to construct.
Here are my basic guide lines before I'm starting to write a mission:
- What is the goal of this mission ( flight practice, "story" like mission )
- What type of airplane involved ( GA, Seaplane, Heavy Duty... )
- Area to conduct the Mission.
- Takeoff and Landing locations, Key points to add Objectives.
- Atmosphere - Time, Weather, airplane payload
Creating the skeleton for your mission:
The following tips are suggestions from my own experience.
When creating a mission file, first I define the "Header" elements and then I add the "Body" elements. I always start with one "Objective" and test that the plugin reads my Mission file. Read the briefer description and test the "[take me there]" button.
Here is a simple base skeleton of a mission data file"
- Write the Header of the mission:
<?xml .... />
<MISSION>
<GlobalSettings ...>....</GlobalSettings>
<Briefer ...> ....
- Write at list One Objective:
<OBJECTIVES>
<Objective id="1".....>
- Write closing Objective
<Objective id="99" .... > - Close Mission
</MISSION>
Other suggestions:
* Do not write a full mission file data and then test it. We all learn from our mistakes from one objective to the other and can copy new and improved content from one objective to the next one. So take your time and build it in steps.
* The last thing you should do, is to indent and add brief comments to the mission file.
You should next read the XSD document, which is based on v2.01.