-
Notifications
You must be signed in to change notification settings - Fork 32
Advanced Configuration Syntax
Out of necessity as things developed, the configuration field has grown to be more capable. While most often left blank, or simply given a string to match against a ModuleEngineConfigs configuration field, this field has expanded to allow more advanced matching syntax especially for use with procedural parts. This page details the more advanced syntax that can be used. It is a bit, OK a lot, kludgey, but it works and once you wrap your head around it is it rather simple. The initial head wrapping though is a bit of a challenge.
Ok let's start at the beginning. No matter how complicated your query gets, at the end of the day you are generating a simple list of parts to be matched. So let's start there, with a simple list.
configuration = RL10A-3,RL10A-3-3,RL10A-3-3A
Rule #1 - List items are comma separated.
No matter how complicated it may get after this, any query will eventually be reduced internally to that. The list indicates to TestFlight which parts are valid. So in the above case, that configuration would be considered to be a match if the part is attached to had an Active MdouleEngineConfigs configuration of any of those three engines. Remember this is checked at runtime either in the Editor or in Flight.
Rule #2 - There must be no spaces before or after your commas. Part1,Part2 is valid. Part1, Part2 is invalid.
Continuing on from our basic list, let's up the complexity a bit. We want to match if we are one engine OR another engine.
configuration = RL10A-3||RL10A-3-3||RL10A-3-3A
Rule #3 - Use || to specify an OR condition
This example actually shows several things. First off, it shows you how to specify an OR condition. At runtime this configuration will match if the active engine config if RL10A-3 OR RL10A-3-3 OR RL10A-3-3A. Secondly you might ask, where did our commas go? Isn't this supposed to be a list? Well in this case we have a list of one item. That entire string is a query for a single item, and internally gets reduced to whichever matches first.
Rule #4 - OR conditions stop at the first match.
The last thing about this example that may have you wondering about is, what is the difference between example #1 and example #2? Don't they do the same thing? Yes. and No. As shown in the examples, yes they do the same thing, and Example #1 would be the preferred method as it would run slightly faster. However, the syntax here can be used in other places in TestFlight, for example in the techTransfer property. The techTransfer property specifies a list of other parts from which the part should transfer Flight Data upon first use. In that case, the two examples would be very different. Example #1 would transfer data from all three of the specified engines, assuming they could be found. Each item in the list would be transferred. In example #2 however, remember that it is actually a list of one item, so data would be transferred from only one of the three engines, whichever one of the three was found first.
You can also combine multiple items into one list item with the AND condition.
condition = RL10A-3-1&&RL10A-3-3,RL10A-3-3A
Rule #5 - Use && to specify an AND condition
Again, like the OR condition, the AND condition collapses to a single item in the final list, but in this case both of these engines are combined and treated as one item. Where might this matter? Again a perfect example is in techTransfer. Consider the following config:
techTransfer = RL10A-1,RL10A-3-1,RL10A-3-3,RL10A-3-3A
techTransferMax = 5000
techTransferGenerationPenalty = 0.10
The above configuration sets up a techTransfer for the configured part, pulling data from the four engines listed in the techTransfer field. It will transfer up to a maximum of 5,000 data units from the four engines combined, and has a generation penalty of 0.10. That last part is the key here. Each item in the query list is treated as a new generation. However much data RL10A-3-1 has, due to the generation penalty it will transfer 20% less. What if you instead wanted to specify that all the -3 series should be treated as one generation? This is where our AND condition comes in.
techTransfer = RL10A-1,RL10A-3-1&&RL10A-3-3&&RL10A-3-3A
techTransferMax = 5000
techTransferGenerationPenalty = 0.10
Our list now only has two actual items in it. The RL10A-1 is the first item, and then the next three engines are all ANDed together to produce a second item.
You can combined, AND and OR conditions in the same list item, or separated in the same list. However bear in mind where you place your commas, in other words be mindful of which conditions collapse into a single item. When both an AND and an OR condition are in the same list item, they are evaluated left to right.
configuration = RL10A-1||RL10A-3-1&&RL10A-3-3
configuration = RL10A-3-1&&RL10A-3-3||RL10A-1
Are not the same.
Rule #6 - AND and OR conditions are evaluated left to right and the first match terminates the condition.
Now it is time to move into the deep end. We started in the shallow section of the pool, and slowly waded out until the water was maybe up to our chests. Now its sink or swim as we jump into more advanced query operators which allows for a lot of power and the cost of complexity.
Operators can be used to do conditional matching such as "X is less than 5" or "Y is between 2 and 10" or "Z = 3.5". They can also be used to say "If the name starts with XYZ".
When using operators your condition statements will have at least two, possibly three parts. The operator, the term and possibly a qualifier. Each part is separated by a *single | character. Be mindful of this. It is a single |. || means OR which we talked about above and is a completely different beast. I know, its confusing, but unfortunately I had limited characters to work with. We will look at each operator in detail, but a couple of quick examples:
condition = >|5|r
condition = $|RL10A
condition = <=>|0-10|h
The simplest of all operators is the Starts With operator. It only has two parts to it and matches any configuration that has a string starting with the specified string.
condition = $|RL10A
This example will match any active engine configuration that starts with the string "RL10A", which means that RL10A-1, RL10A-3, RL10A-3-3, etc will all match this query.
Rule #7 - The $ is a STARTS WITH string operator
Combined these often used queries add five more operators to our toolbox. Say you wanted to match any procedural fuel tank great than 5m in diameter?
condition = >|5|d
Woah what is all that gobblygook? It is simple once you break it down. First as mentioned before we have three parts to this statement. The operator always comes first, so we know that > is our operator, and just like you learned in school this is the greater than operator. The second part is our term, 5 in this case, meaning 5 meters. The third and last part, which is required for any comparison operator is the qualifier. With the first two parts we have the statement 5 meters greater than...But TestFlight needs to know "greater than what?" and that is where the qualifier comes in. This is covered in more detail in the Procedural Parts support text, but in this case the identifier "d" means the diameter of the part. So taking all three parts we have our original goal. Match all parts with a diameter over 5m. Note this is OVER 5m, not EQUALS 5m. 5m will not match, but 5.1 will. We can expand this to match both 5m and above, by saying Greater Than or Equal To:
condition = >=|5|d
The five comparison operators are >, <, <=, >=, and =.
Lastly we have In Range operators, which match based on a given bottom and top end range. These are used in situations where you want to say something like "Match all tanks with a length between 20 and 50 meters":
condition = <>|20-50|h
As with before, we have three parts, and they are always in the same order. Our operator is <> which means In Range Exclusive, meaning it matches anything between the two values but not the values themselves. Next we have the term which in this case is 20-50. Note the - character. This does not mean 20 minus 50, it means 20 is the low end and 50 is the high end for the range check. For any range operator you must specify the low and high end, separated by a - character and no spaces. Lastly we have our qualifier part which in this case specifies Height.
We can also do an In Range Inclusive check, which means in the range including the low and high value like so:
condition = <=>|20-50|h