Changes for page Mission Director Guide

Summary

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

Details

Page properties

Content

...	...	@@ -22,7 +22,7 @@
22	22	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.
23	23
24	24	{{info}}
25		-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;"]]).
	25	+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]]).
26	26
27	27	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."
28	28	{{/info}}
...	...	@@ -84,6 +84,7 @@
84	84	* **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.
85	85	* **Active**: The cue is about to perform the actions. Child cues have entered the waiting state.
86	86
	87	+
87	87	* **Complete**: The cue has finished performing its actions.
88	88	* **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.
89	89
...	...	@@ -155,6 +155,7 @@
155	155
156	156	* 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).
157	157
	159	+
158	158	* 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.
159	159
160	160	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 @@
217	217	{{/code}}
218	218
219	219	{{info}}
220		-Messages printed with <debug_text> are usually only visible when the "scripts" debug filter is enabled, see [[Script debug output>>doc:||anchor="HScriptdebugoutput"]]
	222	+Messages printed with <debug_text> are usually only visible when the "scripts" debug filter is enabled, see Script debug output
221	221	{{/info}}
222	222
223		-Script debug output
224	224
	226	+
225	225	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.
226	226
227	227	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 @@
239	239	{{/info}}
240	240
241	241
	244	+
242	242	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:
243	243
244	244	{{code language="xml"}}
...	...	@@ -289,9 +289,11 @@
289	289	{{/code}}
290	290
291	291	{{warning}}
292		-These examples are definitely **__not__ **examples of good scripting style.
	295	+These examples are definitely <u>not</u> examples of good scripting style.
293	293	{{/warning}}
294	294
	298	+
	299	+
295	295	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.
296	296
297	297	Notes:
...	...	@@ -361,6 +361,8 @@
361	361	This sub-section requires basic knowledge of script expressions.
362	362	{{/info}}
363	363
	369	+
	370	+
364	364	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.
365	365
366	366	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 @@
396	396
397	397	* **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:
398	398
399		-{{code language="xml"}}<debug_text text="static.$foo"/>{{/code}}
	406	+{{code language="xml"}} <debug_text text="static.$foo"/>{{/code}}
400	400	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:
401	401	{{code language="xml"}}<set_value name="$foo" exact="static.$foo"/>{{/code}}
402	402
...	...	@@ -496,10 +496,10 @@
496	496	|true|constant|{{code language="xml"}}null == 0{{/code}}|{{code language="xml"}}true{{/code}}|Integer value 1, useful in Boolean expressions
497	497	|pi|constant|{{code language="xml"}}2 * pi{{/code}}|{{code language="xml"}}6.2831853rad{{/code}}|π as an angle (same as 180deg)
498	498	|()|delimiter|{{code language="xml"}}(2 + 4) * (6 + 1){{/code}}|{{code language="xml"}}42{{/code}}|Parentheses for arithmetic grouping
499		-|[]|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
500		-|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
	506	+|[]|delimiter|{{code language="xml"}}[1, 2, 2+1, 'string']{{/code}}|{{code language="xml"}}[1, 2, 3, 'string']{{/code}}|[[List>>MediaWiki.NULL]] of values
	507	+|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
501	501	|{}|delimiter|{{code language="xml"}}{101, 3}{{/code}}|{{code language="xml"}}'Some text'{{/code}}|Text lookup (page ID and text ID) from TextDB
502		-\\(Note: Braces are also used for [[property lookups>>doc:||anchor="HValueproperties" style="outline-width: 0px !important; user-select: auto !important;"]])
	509	+\\(Note: Braces are also used for [[property lookups>>MediaWiki.NULL]])
503	503	|+|unary|{{code language="xml"}}+21 * (+2){{/code}}|{{code language="xml"}}42{{/code}}|Denotes positive number (no effect)
504	504	|-|unary|{{code language="xml"}}-(21 * -2){{/code}}|{{code language="xml"}}42{{/code}}|Negates the following number
505	505	|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 @@
556	556	{{code language="xml"}}1 ge 3{{/code}}
557	557	\\{{code language="xml"}}1 <= 3{{/code}}|{{code language="xml"}}false{{/code}}|Greater than or equal to
558	558	|(((
559		-
	566	+= =
560	560	)))|binary|{{code language="xml"}}1 + 1 == 2.0{{/code}}|{{code language="xml"}}true{{/code}}|Equal to
561	561	|~!=|binary|{{code language="xml"}}1 + 1 != 2.0{{/code}}|{{code language="xml"}}false{{/code}}|Not equal to
562	562	|and|binary|{{code language="xml"}}true and false{{/code}}|{{code language="xml"}}false{{/code}}|Logical AND (short-circuit semantics)
...	...	@@ -570,6 +570,7 @@
570	570	\\{{code language="xml"}}'T'{{/code}}|Conditional operator ("inline if")
571	571	)))
572	572
	580	+
573	573	=== Operator precedence rules ===
574	574
575	575	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 @@
584	584	* or
585	585	* if/then/else (lowest precedence)
586	586
	595	+
587	587	=== Type conversion ===
588	588
589	589	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 @@
625	625	* 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.
626	626	* <, <=, >, >= 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.
627	627
	637	+
628	628	(% id="categorybroken_macroanchorstrings-and-formatting" %)== Strings and formatting==
629	629
630	630
...	...	@@ -688,16 +688,19 @@
688	688	* null cannot be used as table key (but the number 0 is valid)
689	689	* Lists, tables, groups and buildplans cannot be used as table keys
690	690
	701	+
691	691	These restrictions only apply to the keys, there are no restrictions for values that you assign to them. For example:
692	692
693	693	* {{code language="xml"}}table[]{{/code}} ⟹ creates an empty table
694	694	* {{code language="xml"}}table[{0} = null]{{/code}} ⟹ creates a table that maps the number 0 to null
695	695
	707	+
696	696	* {{code language="xml"}}table[{'$foo'} = 'bar']{{/code}} ⟹ a table that maps the string '$foo' to the string 'bar'
697	697	* {{code language="xml"}}table[$foo = 'bar']{{/code}} ⟹ exactly the same, just a shorter notation for string keys
698	698	* {{code language="xml"}}table[foo = 'bar']{{/code}} ⟹ error, 'foo' does not start with a '$'
699	699	* {{code language="xml"}}table[{1} = [], {2} = table[]] {{/code}} ⟹ a table that maps 1 to an empty list and 2 to an empty table
700	700
	713	+
701	701	Just like lists, tables are stored as references, so it's possible that multiple variables reference the same table (see above).
702	702
703	703	== Value properties ==
...	...	@@ -722,6 +722,7 @@
722	722	* {{code language="xml"}}[].{'count'}{{/code}} ⟹ 0
723	723	* {{code language="xml"}}table[{21} = 42].{21}{{/code}} ⟹ 42
724	724
	738	+
725	725	In most cases the property key is a fixed string, like "name" or "class". You can write this like above:
726	726
727	727	* {{code language="xml"}}[42].{'count'}{{/code}}
...	...	@@ -729,6 +729,7 @@
729	729	* {{code language="xml"}}$ship.{'class'}{{/code}}
730	730	* {{code language="xml"}}table[$foo='bar'].{'$foo'}{{/code}}
731	731
	746	+
732	732	But it is easier just to write the property key without braces, which is equivalent:
733	733
734	734	* {{code language="xml"}}[0].count{{/code}}
...	...	@@ -736,6 +736,7 @@
736	736	* {{code language="xml"}}$ship.class{{/code}}
737	737	* {{code language="xml"}}table[$foo='bar'].$foo{{/code}}
738	738
	754	+
739	739	(In this case, $ship is a variable. All variables start with a "$", so they cannot be confused with keywords.)
740	740
741	741	A list has even more properties:
...	...	@@ -769,6 +769,7 @@
769	769
770	770	* {{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)
771	771
	788	+
772	772	* {{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)
773	773	* {{code language="xml"}}$table.keys.random{{/code}}: A randomly chosen key (which requires that the table is non-empty)
774	774
...	...	@@ -784,6 +784,7 @@
784	784	* {{code language="xml"}}$list.{5}?{{/code}} ⟹ true if $list exists and has the property 5, false otherwise
785	785	* {{code language="xml"}}$table.$key?{{/code}} ⟹ Analogously, true if $table exists and has the string property '$key'
786	786
	804	+
787	787	The question mark can even be applied to variables:
788	788
789	789	* {{code language="xml"}}$list{{/code}} ⟹ The value stored under the name $list, or an error if there is no such variable
...	...	@@ -872,9 +872,11 @@
872	872	* player.**money**: The money in the player's account
873	873	* player.**ship**: The ship the player is currently on (not necessarily the player's ship), or null if the player is on a station
874	874
	893	+
875	875	* player.**primaryship**: The player's own ship (but the player is not necessarily on board)
876	876	* player.**entity**: The actual player object
877	877
	897	+
878	878	* player.**zone**, player.**sector**, player.**cluster**, player.**galaxy**: Location of the player entity
879	879	* player.**copilot**: The co-pilot NPC
880	880
...	...	@@ -901,6 +901,7 @@
901	901	* {{code language="xml"}}$money.formatted.{'formatstring'}{{/code}}
902	902	* {{code language="xml"}}$money.formatted.default{{/code}} (using default format string '%s')
903	903
	924	+
904	904	* {{code language="xml"}}$time.formatted.{'formatstring'}{{/code}}
905	905	* {{code language="xml"}}$time.formatted.default{{/code}} (using default format string '%T')
906	906
...	...	@@ -924,6 +924,7 @@
924	924	* %Cr: Localised "Cr" string
925	925	* %%: A % sign
926	926
	948	+
927	927	Examples:
928	928
929	929	* {{code language="xml"}}(1234Cr).formatted.{'%s'}{{/code}}⟹{{code language="xml"}}'1,234'{{/code}}