Changes for page Mission Director Guide

Last modified by Klaus Meyer on 2025/03/31 16:39

From 32957.1 to 32956.1 From 32963.1 to 32962.1

From version 32962.1

edited by Daniel Turner
on 2023/08/24 10:04

Change comment: There is no comment for this version

To version 32957.1

edited by Daniel Turner
on 2023/08/22 19:09

Change comment: There is no comment for this version

Raw
Rendered

Summary

Page properties (1 modified, 0 added, 0 removed)

Details

Page properties

Content

@@ -22,7 +22,7 @@
  This functionality is only available if the schema files **md.xsd** and **common.xsd** are in the correct folder. If you are editing the XML in the game folder directly, all is well and the files are loaded from the libraries folder. However, if you are editing in a separate folder, copy those XSD files from the libraries folder directly into the folder where your XML files are located.
  {{info}}
--Even if your script is free of XSD errors, that does not mean that the script syntax is correct. For example, there are XML elements that require at least one of multiple attributes, but this requirement cannot be reflected in a schema (apart from documentation text). Please notice the XSD documentation of the elements and attributes, e.g. displayed via tooltips in Visual Studio / Visual Web Developer. Please also note additional requirements for MD cue attributes in this guide (see [[Conditions>>doc:||anchor="HConditions" style="outline-width: 0px !important; user-select: auto !important;"]]).
++Even if your script is free of XSD errors, that does not mean that the script syntax is correct. For example, there are XML elements that require at least one of multiple attributes, but this requirement cannot be reflected in a schema (apart from documentation text). Please notice the XSD documentation of the elements and attributes, e.g. displayed via tooltips in Visual Studio / Visual Web Developer. Please also note additional requirements for MD cue attributes in this guide (see [[NULL|Conditions]]).
  To check for errors, please pay attention to in-game error messages that are produced while your script is imported, and run-time errors while the script runs. The XSD files can help you a lot, but you should not rely on the absence of XSD errors."
  {{/info}}
@@ -84,6 +84,7 @@
  * **Waiting**: Either this is a root cue, or the parent has become active. The cue is checking its conditions and will become active when they are met.
  * **Active**: The cue is about to perform the actions. Child cues have entered the waiting state.
++
  * **Complete**: The cue has finished performing its actions.
  * **Cancelled**: The cue has been cancelled. This state cannot normally be reached but only if a cue actively cancels itself or another cue. No condition checks or actions are performed in this cue or any sub-(sub-)cue.
@@ -155,6 +155,7 @@
  * Use //onfail// if the conditions should be checked only once. The possible attribute values are "//cancel//" and "//complete//". If the conditions are met, the cue will activate and perform the cue actions. Otherwise it's a failure and the cue will be cancelled or completed, based on the onfail attribute. Typically //onfail="cancel"// is used to prevent any further action. //onfail="complete"// can be used to continue with the sub-cues even in case of failure (but skipping the current cue actions).
++
  * With //checkinterval//, you can specify a constant time interval between condition checks. The conditions will be checked regularly forever until they are met, unless the cue's state is changed explicitly by an external event.
  Additionally, you can use the attribute **checktime** to set the time of the first condition check (also possible in combination with //onfail//). The //checktime// can be an expression with variables and is evaluated when the cue is enabled (when the condition checks would normally start ΓÇô for root cues that happens at game start, otherwise after the parent cue becomes active).
@@ -217,11 +217,11 @@
  {{/code}}
  {{info}}
--Messages printed with <debug_text> are usually only visible when the "scripts" debug filter is enabled, see [[Script debug output>>doc:||anchor="HScriptdebugoutput"]]
++Messages printed with <debug_text> are usually only visible when the "scripts" debug filter is enabled, see Script debug output
  {{/info}}
--Script debug output
++
  Each child action in a <do_any> node can have a //**weight**// attribute, which can be used to control the random selection of an action node. The default weight of a child node is 1.
  Also available is **<do_if>**, which completes the enclosed action(s) only if one provided value is non-null or matches another. Directly after a <do_if> node, you can add one or more **<do_elseif>** nodes to perform additional checks only in case the previous conditions were not met. The node **<do_else>** can be used directly after a <do_if> or a <do_elseif>. It is executed only if none of the conditions are met.
@@ -239,6 +239,7 @@
  {{/info}}
++
  Library cues are written like normal cues, they are also defined in a <cues> node, just with the difference that the XML tag is called library instead of cue:
  {{code language="xml"}}
@@ -289,9 +289,11 @@
  {{/code}}
  {{warning}}
--These examples are definitely **__not__ **examples of good scripting style.
++These examples are definitely <u>not</u> examples of good scripting style.
  {{/warning}}
++
++
  So when writing the library, you don't have to worry about name confusion, just use the names of cues in your library and it will work as expected when the library is used. Names of cues that do not belong to the library will not be available in expressions (see Foo in the example above), however, names of other libraries in the file are available when referencing them in the ref attribute.
  Notes:
@@ -361,6 +361,8 @@
  This sub-section requires basic knowledge of script expressions.
  {{/info}}
++
++
  In case of instances with sub-instances, you will often want to access a related instance from the current one. Like in the non-instance case, you can simply write the cue name in an expression to reference that cue. However, you should be aware of the pitfalls that are accompanied by this.
  When you use a cue name from the same script in an expression, it will always be resolved to some cue - usually a static cue, even if it is still in the disabled state, but it can also be an instance, if it is "related" to the current one.
@@ -396,7 +396,7 @@
  * **Conditions with results:** If the instantiating cue has conditions with results, those results are stored in variables - but in the variables of the static cue, not of the instance! So in the <actions> you have to access the variables via the **static **keyword:
--{{code language="xml"}}<debug_text text="static.$foo"/>{{/code}}
++{{code language="xml"}}  <debug_text text="static.$foo"/>{{/code}}
  It may even be necessary to copy the variables over to the instance because the static variables can be overwritten by the next condition check:
  {{code language="xml"}}<set_value name="$foo" exact="static.$foo"/>{{/code}}
@@ -496,10 +496,10 @@
  |true|constant|{{code language="xml"}}null == 0{{/code}}|{{code language="xml"}}true{{/code}}|Integer value 1, useful in Boolean expressions
  |pi|constant|{{code language="xml"}}2 * pi{{/code}}|{{code language="xml"}}6.2831853rad{{/code}}|╧Ç as an angle (same as 180deg)
  |()|delimiter|{{code language="xml"}}(2 + 4) * (6 + 1){{/code}}|{{code language="xml"}}42{{/code}}|Parentheses for arithmetic grouping
--|[]|delimiter|{{code language="xml"}}[1, 2, 2+1, 'string']{{/code}}|{{code language="xml"}}[1, 2, 3, 'string']{{/code}}|[[List>>doc:||anchor="HLists" style="outline-width: 0px !important; user-select: auto !important;"]] of values
--|table[]|delimiter|{{code language="xml"}}table[$foo='bar', {1+1}=40+2]{{/code}}|{{code language="xml"}}table[$foo='bar', {2}=42]{{/code}}|[[Table>>doc:||anchor="HTables" style="outline-width: 0px !important; user-select: auto !important;"]] of values
++|[]|delimiter|{{code language="xml"}}[1, 2, 2+1, 'string']{{/code}}|{{code language="xml"}}[1, 2, 3, 'string']{{/code}}|[[List>>MediaWiki.NULL]] of values
++|table[]|delimiter|{{code language="xml"}}table[$foo='bar', {1+1}=40+2]{{/code}}|{{code language="xml"}}table[$foo='bar', {2}=42]{{/code}}|[[Table>>MediaWiki.NULL]] of values
  |{}|delimiter|{{code language="xml"}}{101, 3}{{/code}}|{{code language="xml"}}'Some text'{{/code}}|Text lookup (page ID and text ID) from TextDB
--\\(Note: Braces are also used for [[property lookups>>doc:||anchor="HValueproperties" style="outline-width: 0px !important; user-select: auto !important;"]])
++\\(Note: Braces are also used for [[property lookups>>MediaWiki.NULL]])
  |+|unary|{{code language="xml"}}+21 * (+2){{/code}}|{{code language="xml"}}42{{/code}}|Denotes positive number (no effect)
  |-|unary|{{code language="xml"}}-(21 * -2){{/code}}|{{code language="xml"}}42{{/code}}|Negates the following number
  |not|unary|{{code language="xml"}}not (21 == 42){{/code}}|{{code language="xml"}}true{{/code}}|Yields true if the following expression is false (equal to zero), false otherwise
@@ -556,7 +556,7 @@
  {{code language="xml"}}1 ge 3{{/code}}
  \\{{code language="xml"}}1 <= 3{{/code}}|{{code language="xml"}}false{{/code}}|Greater than or equal to
  |(((
--
++=  =
  )))|binary|{{code language="xml"}}1 + 1 == 2.0{{/code}}|{{code language="xml"}}true{{/code}}|Equal to
  |~!=|binary|{{code language="xml"}}1 + 1 != 2.0{{/code}}|{{code language="xml"}}false{{/code}}|Not equal to
  |and|binary|{{code language="xml"}}true and false{{/code}}|{{code language="xml"}}false{{/code}}|Logical AND (short-circuit semantics)
@@ -570,6 +570,7 @@
  \\{{code language="xml"}}'T'{{/code}}|Conditional operator ("inline if")
  )))
++
  === Operator precedence rules ===
  You can group sub-expressions using parentheses, but if you don't, the following order of operations is applied, so that 5-1+2*3 == 10 as you would expect. The order is the same as in the table above, but there are operators with the same precedence - these are applied from left to right.
@@ -584,6 +584,7 @@
  * or
  * if/then/else (lowest precedence)
++
  === Type conversion ===
  When a binary arithmetic operator is used on numbers of different types, they will be converted to a suitable output type. The resulting type depends on whether a unit data type is involved (types that are not plain integers or floats). The following cases may occur:
@@ -625,6 +625,7 @@
  * Unlike != and ==, the comparison operators <, <=, >, >= are only supported **for numeric values**, **difficulty levels**, and **attention levels**. Comparing other non-numeric values will result in an error and an undefined result.
  * <, <=, >, >= cannot be used in XML directly, so lt, le, gt, ge are provided as alternatives. In some cases you won't have to use them, though - using [[range checks>>MediaWiki.NULL]] with additional XML attributes can be more readable.
++
  (% id="categorybroken_macroanchorstrings-and-formatting" %)== Strings and formatting==
@@ -688,16 +688,19 @@
  * null cannot be used as table key (but the number 0 is valid)
  * Lists, tables, groups and buildplans cannot be used as table keys
++
  These restrictions only apply to the keys, there are no restrictions for values that you assign to them. For example:
  * {{code language="xml"}}table[]{{/code}} ⟹ creates an empty table
  * {{code language="xml"}}table[{0} = null]{{/code}} ⟹ creates a table that maps the number 0 to null
++
  * {{code language="xml"}}table[{'$foo'} = 'bar']{{/code}} ⟹ a table that maps the string '$foo' to the string 'bar'
  * {{code language="xml"}}table[$foo = 'bar']{{/code}} ⟹ exactly the same, just a shorter notation for string keys
  * {{code language="xml"}}table[foo = 'bar']{{/code}} ⟹ error, 'foo' does not start with a '$'
  * {{code language="xml"}}table[{1} = [], {2} = table[]] {{/code}} ⟹ a table that maps 1 to an empty list and 2 to an empty table
++
  Just like lists, tables are stored as references, so it's possible that multiple variables reference the same table (see above).
  == Value properties ==
@@ -722,6 +722,7 @@
  * {{code language="xml"}}[].{'count'}{{/code}} ⟹ 0
  * {{code language="xml"}}table[{21} = 42].{21}{{/code}} ⟹ 42
++
  In most cases the property key is a fixed string, like "name" or "class". You can write this like above:
  * {{code language="xml"}}[42].{'count'}{{/code}}
@@ -729,6 +729,7 @@
  * {{code language="xml"}}$ship.{'class'}{{/code}}
  * {{code language="xml"}}table[$foo='bar'].{'$foo'}{{/code}}
++
  But it is easier just to write the property key without braces, which is equivalent:
  * {{code language="xml"}}[0].count{{/code}}
@@ -736,6 +736,7 @@
  * {{code language="xml"}}$ship.class{{/code}}
  * {{code language="xml"}}table[$foo='bar'].$foo{{/code}}
++
  (In this case, $ship is a variable. All variables start with a "$", so they cannot be confused with keywords.)
  A list has even more properties:
@@ -769,6 +769,7 @@
  * {{code language="xml"}}$table.keys.list{{/code}}: Yields a list of all keys in the table (reliably sorted by key if all keys are numeric)
++
  * {{code language="xml"}}$table.keys.sorted{{/code}}: Yields a list of all keys in the table, sorted by their associated values (which requires that all values are numeric)
  * {{code language="xml"}}$table.keys.random{{/code}}: A randomly chosen key (which requires that the table is non-empty)
@@ -784,6 +784,7 @@
  * {{code language="xml"}}$list.{5}?{{/code}} ⟹ true if $list exists and has the property 5, false otherwise
  * {{code language="xml"}}$table.$key?{{/code}} ⟹ Analogously, true if $table exists and has the string property '$key'
++
  The question mark can even be applied to variables:
  * {{code language="xml"}}$list{{/code}} ⟹ The value stored under the name $list, or an error if there is no such variable
@@ -849,7 +849,6 @@
  \\faction.argongovernment|Factions
  )))
--{{id name="typeof" /}}
  {{info}}
  With the ''typeof'' operator you can get the datatype of any expression and compare it with what you expect, for example:
@@ -873,9 +873,11 @@
  * player.**money**: The money in the player's account
  * player.**ship**: The ship the player is currently on (not necessarily the player's ship), or null if the player is on a station
++
  * player.**primaryship**: The player's own ship (but the player is not necessarily on board)
  * player.**entity**: The actual player object
++
  * player.**zone**, player.**sector**, player.**cluster**, player.**galaxy**: Location of the player entity
  * player.**copilot**: The co-pilot NPC
@@ -902,6 +902,7 @@
  * {{code language="xml"}}$money.formatted.{'formatstring'}{{/code}}
  * {{code language="xml"}}$money.formatted.default{{/code}} (using default format string '%s')
++
  * {{code language="xml"}}$time.formatted.{'formatstring'}{{/code}}
  * {{code language="xml"}}$time.formatted.default{{/code}} (using default format string '%T')
@@ -925,6 +925,7 @@
  * %Cr: Localised "Cr" string
  * %%: A % sign
++
  Examples:
  * {{code language="xml"}}(1234Cr).formatted.{'%s'}{{/code}}⟹{{code language="xml"}}'1,234'{{/code}}

Changes for page Mission Director Guide

Summary

Details

Navigation

Applications