- You read PART 1 of selection tutorial.
- You are familiar with MXPAD script concept and how to start/stop it.
If this is your first time with Mission-X as a concept, I would even suggest to write a simple mission without "embedded scripts", then add a simple script logic to better understand the flow of the plugin with it. Last will be to add MXPAD scripting, not that it is more complicated, but you need to remember that it is there to allow designer to:
- Write a "conversation like" flow for the mission and
- Allow interaction with the simmer, but as a flow and without selection.
Example: "Please turn on Taxi light", simmer does not need to choose an option, just to do it. We handle the timer and logic outcome in code. - Allow interaction with simmer through the "selection" API functions (added by "ptimib" in v3.0.206). In this case we are waiting for the simmer to choose between options indefinitely.
In this follow up tutorial I'll demonstrate how to send a message to the simmer and then "ask" him/her to do an action on a selection option. This is a simple example, but even complex ones share same methodology.
Demonstration Detail
We will send a "hello world" through the MXPAD interface, and then ask the simmer to press the "continue..." option to continue the conversation flow.
How we will control the flow of code:
In order to control flow of script between plugin calls, we will use a global variable by the name: "iStep" we can declare it in the mission's XML file under "<embedded_scripts>" element, or create it inside the script itself (less desirable).
I think it is easier to define it in our XML file.
How will we distinguish between selections:
Another control element is the "custom dataref" - "missionx/mxSelection".
This dataref is created by Mission-X plugin, and it sole purpose is to hold the "selection" value, so scripts can evaluate it.
The "missionx/mxSelection" dataref should be initialized with the values "-1 or 0", max value should be "4".
Our first step would be to define these two control mechanism in Mission-X mission file:
The dataref "mxSel" will point to the custom dataref "missionx/mxSelection" and will hold the users selection.
From STEP 1, of the tutorial, we know that the first MXPAD function we call is: "start_intro". Therefore we will implement our first "conversation" handling inside it.
Lets display a snippet from it:
We can see that the first thing we do is to read the "control variable".
We start the script by reading the "control parameter iStep" and in the function being called we branch the code to handle the expected step logic.
Creating a message
You can see that when "iStep" value is "1", we create two text messages using "fn_create_new_mxpad_message()" function. Each message should have a unique name.
Since there is no sound channel (a file that will "narrate" the message), we commented out the function: "fn_set_mxpad_media_channel()".
Last: we send the new message using "fn_send_comm_message()" function.
Handling next code iteration
At the end of the messages, we increase the "iStep" value and store it, so in the next call iteration the "start_intro()" function will only handle "iStep=2" logic.
Now we will create the "selection options", in this example we first send the messages and only then display the selections, but you can vary the flow.
Using the "fn_is_mxpad_queue_empty()" function we make sure that the code in the "if..." block won't be executed while there are messages being broadcast, or waiting to be sent.
Reset selection dataref
Using the "fn_set_dref_value(...)" we rest the selection custom dataref, so we won't use older selection by mistake.
Progress Logic and define the selection
For the "selection options" to be displayed, we do not need to "render" it each flight pass. We just need to define it once, and it will be "displayed" indefinitely.
Using "fn_create_mxpad_selection()" store the selection definitions.
How to write selections
fn_create_mxpad_selection("#SEL#1 - Click to Continue...")
The plugin will parse the string you send to the "fn_create_mxpad_selection" function and construct the options from it. The "#SEL#" divides the selection options:
- #SEL# - This means add selection. We should have no more than 4 (four) selection options (in v3.0.206)
"#SEL#Option 1...#SEL#Option 2."
The last step would be to handle the selection action.
In our case it will be done as part of "iStep = 3" logic block of code.
The main logic for "iStep = 3" is to "fetch" the "custom dataref" mxSel and check its value.
sel = fn_get_dref_value("mxSel")
if sel = 1 then
Do Something
Once user picked the "correct" value we can progress the "communication".
In our case, we display a new "selection option", this time it has 4 options, but the rest of the code won't be discussed here, you can read it in the "selection demo mission".
This is basically the building blocks for the "selection feature". You can design simple or complex ones, but please do not use it if you really don't need it. In most cases a "timer" based decision will be sufficient.
In very complex conversation interaction, I would suggest to split the logic to several big functions, and in them use "iStep" to control their specific logic content. It might simplify the code handling.
In this demo we used one function and handle all options and flow.
Summary
I hope that in this second tutorial, you receive a good insight of how the MXPAD selection feature was implemented, and how to define it and control it in script. Please do remember that script flow might need attention in both the XML mission file and in your script code, and as I stated before, start with simple script implementation before "rushing" to MXPAD conversation flow handling.
For any question or suggestion, please contact me directly to my e-mail.
Have great flight simming
Saar