In this short news letter I'll try to explain how to use the "selection" option implemented in Mission-X plugin. This is will PART 1 of the tutorial, so read to the end.
Few months back, I've been approached by "ptimib", he asked me to implement a "selection" option into the plugin. Long story short, I agreed to allow him access to the project code and to add it. My main role at the beginning was to help him get familiar with the code and how to work with the VS tools. After few weeks he was able to present a working code that I later merged to the plugin master code.
Why am I writing all this ? Well, first because it was a pleasure to work with him, he is also the first programmer to contribute directly to the code and I'm happy and proud he did it. I really hope more people will join and add their own touch or features to the plugin, I'll be more than happy to get some help from contributors.
What was added with the selection feature
- You can define up to 4 selection options - only through external script (specifically MXPAD script).
- [optional] You can map each selection option to "keyboard" or "joystick button" (if you have any left unusable).
- You can pick the options using mouse.
- More headache in terms of code management and flow (well, this is not really a feature but an outcome...)
How to design a selection option
I believe that the first step to implement a selection, is to first understand what you want to achieve, is the interaction of the simmer necessary or we can skip it.
Implementing a selection code flow, is not an easy fit from script perspective. It is also not complected, it just need careful attention to the flow of the code, so you will branch it correctly.
In this "demo mission" we are going to display 2 usages of "selection options".
The first, will just ask the simmer to "press me to continue".
The second, will ask the simmer to pick an action to do on the plane (options 1..3) while the 4th one will continue.
In the demo, the selection outcome will just print: "you pressed X" and will re-draw the selection options until you will press "continue" (the 4th option).
So understanding what you want to "ask" from the simmer and how to branch the flow of the interaction is crucial to the success of the implementation.
In the following tutorial we will use the example from "mxpad_basic_selection_example.xml" file.
The other thing that we need to decide when we write the script to handle the simmer decisions, is how to handle the branching of the script, meaning, how to handle the outcome of the simmer selections, which part of the plugin or script will handle selection drawing options and so on.
There are two options that I can think of, without giving this much thought:
Option 1: Store selection progress in a global variable, it can be a number, and branch the code using the value. The whole code resides in one "function" or "script" and we handle branching using simple "if..then" statements.
Let's assume that "iStep" is a global variable that represent the progress of the simmer in the dialog.
If the value is "1", then we display "selection option 1".
If the value is "2", then we display "selection options 2".
Once user pick the "continue" option, there is no more selections, so the progress is "linear" and not repeatable (in most cases).
Option 2: We will use functions for each part of the "selection" and "mxpad" code, so it might be easier to maintain and read.
Meaning, every time we want MXPAD script to handle different set of logic, we will call the relevant function using the: "fn_set_mxpad_next_function". That way, in the next iteration only the function code will be called (!! please be advice that the function "fn_set_mxpad_next_function" will be simplified in build v3.0.208 ).
There is no one way to do this, and you might think of a third or forth way, but it is up to you to make it easy to maintain and optimize.
In the following examples, I used the first option, I based it on "ptimib" internal demonstration.
How do we implement the selection feature ?
Since the "selection" option is part of the MXPAD window, the code that deals with it must be driven from an MXPAD script.
So first things first, we need to define an MXPAD script and call it from our mission.
Here is a snippet:
<mxpad name="mxPad1" manage_script="selection_demo_mxpad-01.bas" starting_function="start_intro" enabled="yes" />
The main script is: "selection_demo_mxpad-01.bas" and the first function to call is: "start_intro".
Now we need to activate the MXPAD script.
We need a task in an Objective that will be based on a "script", and that script will start our MXPAD.
You can see that the task can be "mandatory" (this was not supported prior to v3.0.206).
Let's check the "tasks" script that starts our "MXPAD":
I know I rant here quite a lot, but I think that the basics of the MXPAD implementation are important to understand the whole concept of embedded scripting in the plugin. Task and Trigger scripts are simpler to implement since they do not need a starting function, but this should be the most complicated part in the design between XML and the script file.
This is the first step in implementing "Selection Options", in MXPAD scripts.
We saw how to define an MXPAD, and how to start it. When it comes to script work, there are probably two locations we need to handle all the time. The mission XML file and the script file.
So now we need to implement a selection option....
In the second post I'll continue implementation of a simple selection. The more complex one, you should just read from the demo mission after understanding the basics.
Until next time, happy flying.