Changes for page Mission Director Guide
Last modified by Klaus Meyer on 2025/03/31 16:39
From version 32970.4
edited by Owen Lake
on 2023/10/10 15:49
on 2023/10/10 15:49
Change comment:
There is no comment for this version
To version 32973.3
edited by Heinrich Unrau
on 2024/10/17 13:13
on 2024/10/17 13:13
Change comment:
There is no comment for this version
Summary
-
Page properties (2 modified, 0 added, 0 removed)
Details
- Page properties
-
- Author
-
... ... @@ -1,1 +1,1 @@ 1 -xwiki:XWiki. Owen1 +xwiki:XWiki.Heinrich - Content
-
... ... @@ -407,11 +407,11 @@ 407 407 408 408 Most of the attribute values in actions and conditions are interpreted as script expressions and parsed accordingly. An expression is a phrase that can be evaluated to a single value. The simplest expressions are actual numeric values and strings, so called **literals:** 409 409 410 -* {{code language="xml"}}0{{/code}} 411 -* {{code language="xml"}}0772{{/code}} 412 -* {{code language="xml"}}3.14159{{/code}} 413 -* {{code language="xml"}}5e12{{/code}} 414 -* {{code language="xml"}}0xCAFE{{/code}} 410 +* {{code language="xml"}}0{{/code}}(integer number) 411 +* {{code language="xml"}}0772{{/code}}(leading 0 means octal integer number) 412 +* {{code language="xml"}}3.14159{{/code}}(floating point number) 413 +* {{code language="xml"}}5e12{{/code}}(float in exponent notation, "times ten to the power of") 414 +* {{code language="xml"}}0xCAFE{{/code}}(hexadecimal integer number) 415 415 416 416 {{info}} 417 417 Since octal numbers are hardly ever used (usually unknowingly), the parser is will produce a warning if an octal number is encountered." ... ... @@ -420,7 +420,7 @@ 420 420 You can write string literals by putting the string in single quotes: 421 421 422 422 * {{code language="xml"}}'Hello world'{{/code}} 423 -* {{code language="xml"}}''{{/code}} 423 +* {{code language="xml"}}''{{/code}}(empty string) 424 424 * {{code language="xml"}}'String with a line break\n'{{/code}} 425 425 426 426 {{info}} ... ... @@ -432,12 +432,12 @@ 432 432 433 433 Numbers can have a suffix that determines their numeric type. There are also numerical data types like "money" or "time" which can only be expressed by using an appropriate unit suffix: 434 434 435 -* {{code language="xml"}}5000000000L{{/code}} 436 -* {{code language="xml"}}1f{{/code}} 437 -* {{code language="xml"}}1000Cr{{/code}} 438 -* {{code language="xml"}}500m{{/code}} 439 -* {{code language="xml"}}10s{{/code}} 440 -* {{code language="xml"}}1h{{/code}} 435 +* {{code language="xml"}}5000000000L{{/code}}(large integer) 436 +* {{code language="xml"}}1f{{/code}}(floating point number, same as 1.0, just 1 would be an integer) 437 +* {{code language="xml"}}1000Cr{{/code}}(Money in Credits, converted to 100000 cents automatically) 438 +* {{code language="xml"}}500m{{/code}}(Length in metres) 439 +* {{code language="xml"}}10s{{/code}}(Time in seconds) 440 +* {{code language="xml"}}1h{{/code}}(Time in hours, which is converted to 3600s automatically) 441 441 442 442 A space between number and suffix is allowed. 443 443 ... ... @@ -522,20 +522,36 @@ 522 522 {{code language="xml"}}tan(-45deg){{/code}} 523 523 \\{{code language="xml"}}tan(45deg){{/code}}| 524 524 {{code language="xml"}}-1.0{{/code}} 525 -\\{{code language="xml"}}1.0{{/code}}|Tangent (function-style, parentheses required) 525 +\\{{code language="xml"}}1.0{{/code}}|((( 526 +Tangent (function-style, parentheses required) 527 + 528 +Available from X4 v7.0 529 +))) 526 526 |asin|unary| 527 527 {{code language="xml"}}asin(-0.5f){{/code}} 528 528 \\{{code language="xml"}}asin(1){{/code}}| 529 529 {{code language="xml"}}-0.523599rad{{/code}} 530 -\\{{code language="xml"}}1.5708rad{{/code}}|Inverse sine (function-style, parentheses required) 534 +\\{{code language="xml"}}1.5708rad{{/code}}|((( 535 +Inverse sine (function-style, parentheses required) 536 + 537 +Available from X4 v7.0 538 +))) 531 531 |acos|unary| 532 532 {{code language="xml"}}acos(-0.5f){{/code}} 533 533 \\{{code language="xml"}}acos(1.0f){{/code}}| 534 534 {{code language="xml"}}2.0944rad{{/code}} 535 -\\{{code language="xml"}}0rad{{/code}}|Inverse cosine (function-style, parentheses required) 543 +\\{{code language="xml"}}0rad{{/code}}|((( 544 +Inverse cosine (function-style, parentheses required) 545 + 546 +Available from X4 v7.0 547 +))) 536 536 |atan|unary| 537 537 {{code language="xml"}}atan(1.0f){{/code}}| 538 -{{code language="xml"}}0.785398rad{{/code}}|Inverse tangent (function-style, parentheses required) 550 +{{code language="xml"}}0.785398rad{{/code}}|((( 551 +Inverse tangent (function-style, parentheses required) 552 + 553 +Available from X4 v7.0 554 +))) 539 539 |sqrt|unary|{{code language="xml"}}sqrt(2){{/code}}|{{code language="xml"}}1.414213LF{{/code}}|Square root (function-style, parentheses required) 540 540 |exp|unary|{{code language="xml"}}exp(1){{/code}}|{{code language="xml"}}2.71828LF{{/code}}|Exponential function (function-style, parentheses required) 541 541 |log|unary|{{code language="xml"}}log(8) / log(2){{/code}}|{{code language="xml"}}3.0LF{{/code}}|Natural logarithm (function-style, parentheses required) ... ... @@ -614,8 +614,8 @@ 614 614 615 615 There is a way to convert a number into a different type manually: You append the corresponding suffix to a sub-expression in parentheses, like this: 616 616 617 -* {{code language="xml"}}(1 + 1)f{{/code}} 618 -* {{code language="xml"}}(1h) m / (180deg) i{{/code}} 633 +* {{code language="xml"}}(1 + 1)f{{/code}}⟹ {{code language="xml"}}2f{{/code}} ⟹ {{code language="xml"}}2.0{{/code}} 634 +* {{code language="xml"}}(1h) m / (180deg) i{{/code}}⟹ {{code language="xml"}}(3600s) m / (3.14rad) i{{/code}} ⟹ {{code language="xml"}}3600m / 3{{/code}} ⟹ {{code language="xml"}}1200m{{/code}} 619 619 620 620 When converting to a non-default unit type, this means you interpret the number as in the given units: "{{code language="xml"}}(1km + 500m)h{{/code}}" means that you interpret 1500m as 1500 hours, so the resulting value will be 1500x3600 seconds. (As stated above, the default unit for a length is metres.) 621 621 ... ... @@ -623,8 +623,8 @@ 623 623 624 624 Every data type can be combined with a string with the + operator, and will be converted to a string representation. That way you can also concatenate strings and numbers: 625 625 626 -* {{code language="xml"}}'One plus one is equal to ' + (1+1) + '.'{{/code}} 627 -* {{code language="xml"}}'One plus one is not equal to ' + 1 + 1 + '.'{{/code}} 642 +* {{code language="xml"}}'One plus one is equal to ' + (1+1) + '.'{{/code}}⟹ {{code language="xml"}}'One plus one is equal to 2.'{{/code}} 643 +* {{code language="xml"}}'One plus one is not equal to ' + 1 + 1 + '.'{{/code}}⟹ {{code language="xml"}}'One plus one is not equal to 11.'{{/code}} 628 628 629 629 As you can see, operators of the same precedence (+ in this case) are always evaluated from left to right. 630 630 ... ... @@ -656,9 +656,9 @@ 656 656 \\**[New as of X Rebirth 4.0]** 657 657 \\ With the formatting syntax above, it is even possible to control how the parameter is formatted, using modifiers between "%" and the parameter specifier ("s" or the parameter number): 658 658 659 -* {{code language="xml"}}'%,s'.[12345678]{{/code}} 660 -* {{code language="xml"}}'%.3s'.[123.4]{{/code}} 661 -* {{code language="xml"}}'%,.1s'.[12345.67]'{{/code}} 675 +* {{code language="xml"}}'%,s'.[12345678]{{/code}}⟹ {{code language="xml"}}'12,345,678'{{/code}} (the "," modifier shows a number with thousands separators, correctly localised) 676 +* {{code language="xml"}}'%.3s'.[123.4]{{/code}}⟹ {{code language="xml"}}'123.400'{{/code}} (show 3 fractional digits, rounding half away from zero - decimal point correctly localised) 677 +* {{code language="xml"}}'%,.1s'.[12345.67]'{{/code}}⟹ {{code language="xml"}}'12,345.7'{{/code}} (combination of the above) 662 662 663 663 Additional remarks: 664 664 ... ... @@ -703,13 +703,13 @@ 703 703 704 704 These restrictions only apply to the keys, there are no restrictions for values that you assign to them. For example: 705 705 706 -* {{code language="xml"}}table[]{{/code}} 707 -* {{code language="xml"}}table[{0} = null]{{/code}} 722 +* {{code language="xml"}}table[]{{/code}}⟹ creates an empty table 723 +* {{code language="xml"}}table[{0} = null]{{/code}}⟹ creates a table that maps the number 0 to null 708 708 709 -* {{code language="xml"}}table[{'$foo'} = 'bar']{{/code}} 710 -* {{code language="xml"}}table[$foo = 'bar']{{/code}} 711 -* {{code language="xml"}}table[foo = 'bar']{{/code}} 712 -* {{code language="xml"}}table[{1} = [], {2} = table[]] {{/code}} 725 +* {{code language="xml"}}table[{'$foo'} = 'bar']{{/code}}⟹ a table that maps the string '$foo' to the string 'bar' 726 +* {{code language="xml"}}table[$foo = 'bar']{{/code}}⟹ exactly the same, just a shorter notation for string keys 727 +* {{code language="xml"}}table[foo = 'bar']{{/code}}⟹ error, 'foo' does not start with a '$' 728 +* {{code language="xml"}}table[{1} = [], {2} = table[]] {{/code}}⟹ a table that maps 1 to an empty list and 2 to an empty table 713 713 714 714 Just like lists, tables are stored as references, so it's possible that multiple variables reference the same table (see above). 715 715 ... ... @@ -730,10 +730,10 @@ 730 730 731 731 You can look up a property by appending a dot and the key in curly braces: 732 732 733 -* {{code language="xml"}}[100, 200, 300, 400].{1}{{/code}} 734 -* {{code language="xml"}}[100, 200, ['Hello ', 'world']] .{3}.{2}{{/code}} 735 -* {{code language="xml"}}[].{'count'}{{/code}} 736 -* {{code language="xml"}}table[{21} = 42].{21}{{/code}} 749 +* {{code language="xml"}}[100, 200, 300, 400].{1}{{/code}}⟹ 100 (reading the first element) 750 +* {{code language="xml"}}[100, 200, ['Hello ', 'world']] .{3}.{2}{{/code}}⟹ 'world' (second element of the inner list, which is the third element of the outer list) 751 +* {{code language="xml"}}[].{'count'}{{/code}}⟹ 0 752 +* {{code language="xml"}}table[{21} = 42].{21}{{/code}}⟹ 42 737 737 738 738 In most cases the property key is a fixed string, like "name" or "class". You can write this like above: 739 739 ... ... @@ -757,19 +757,19 @@ 757 757 758 758 **min'** and '**max'** return the minimum or maximum (all elements have to be numeric) 759 759 760 -* {{code language="xml"}}[1, 6, 8].min{{/code}} 776 +* {{code language="xml"}}[1, 6, 8].min{{/code}}⟹ 1 761 761 762 762 **average'** returns the average (but all element types have to be compatible) 763 763 764 -* {{code language="xml"}}[1, 6, 8].average{{/code}} 780 +* {{code language="xml"}}[1, 6, 8].average{{/code}}⟹ 5 765 765 766 766 **indexof'** is followed by another property, and the index of the first occurence of that key in the list is returned, or 0 if it's not in the list 767 767 768 -* {{code language="xml"}}[1, 6, 8].indexof.{8}{{/code}} 784 +* {{code language="xml"}}[1, 6, 8].indexof.{8}{{/code}}⟹ 3 769 769 770 770 **clone'** creates a shallow copy of the list (i.e. lists that are contained as elements in the list are not copied, only the reference to them) 771 771 772 -* {{code language="xml"}}[1, 6, 8].clone{{/code}} 788 +* {{code language="xml"}}[1, 6, 8].clone{{/code}}⟹ {{code language="xml"}}[1, 6, 8]{{/code}} 773 773 774 774 A table has different properties: 775 775 ... ... @@ -793,20 +793,20 @@ 793 793 794 794 If you look up a property that does not exist, there will be an error, and the result will be null. To test whether a property exists, you can append a question mark "?" to the lookup, which yields true or false: 795 795 796 -* {{code language="xml"}}$list.{5}{{/code}} 797 -* {{code language="xml"}}$list.{5}?{{/code}} 798 -* {{code language="xml"}}$table.$key?{{/code}} 812 +* {{code language="xml"}}$list.{5}{{/code}}⟹ The fifth element of a list - however, if $list has less than 5 elements (and if it's also not a table with the key 5), there will be an error 813 +* {{code language="xml"}}$list.{5}?{{/code}}⟹ true if $list exists and has the property 5, false otherwise 814 +* {{code language="xml"}}$table.$key?{{/code}}⟹ Analogously, true if $table exists and has the string property '$key' 799 799 800 800 The question mark can even be applied to variables: 801 801 802 -* {{code language="xml"}}$list{{/code}} 803 -* {{code language="xml"}}$list?{{/code}} 818 +* {{code language="xml"}}$list{{/code}}⟹ The value stored under the name $list, or an error if there is no such variable 819 +* {{code language="xml"}}$list?{{/code}}⟹ true if the variable exists, false otherwise 804 804 805 805 To look up the value of a property although it may not exist, you can use the at-sign "@" as prefix: 806 806 807 -* {{code language="xml"}}@$list.{5}{{/code}} 808 -* {{code language="xml"}}@$list{{/code}} 809 -* {{code language="xml"}}@$list.{5}.{1}{{/code}} 823 +* {{code language="xml"}}@$list.{5}{{/code}}⟹ The result of the $list lookup if $list exists and has the property 5, otherwise null (without error message) 824 +* {{code language="xml"}}@$list{{/code}}⟹ The list if this variable exists, null otherwise 825 +* {{code language="xml"}}@$list.{5}.{1}{{/code}}⟹ The first element of the fifth element of $list, if it exists, null otherwise 810 810 811 811 As you can see, an error is already prevented if any link in the property chain does not exist. But use the @ prefix with care, since error messages are really helpful for detecting problems in your scripts. The @ prefix only suppresses property-related error messages and does not change any in-game behaviour. 812 812 ... ... @@ -914,10 +914,10 @@ 914 914 \\Numbers don't have any properties, except for money and time: They have a "**formatted**" property, which allows you to get a custom string representation with more advanced options than the [[generic formatting method>>||anchor="HStringsandformatting" style="outline-width: 0px !important; user-select: auto !important;"]] for numbers. 915 915 916 916 * {{code language="xml"}}$money.formatted.{'formatstring'}{{/code}} 917 -* {{code language="xml"}}$money.formatted.default{{/code}} 933 +* {{code language="xml"}}$money.formatted.default{{/code}}(using default format string '%s') 918 918 919 919 * {{code language="xml"}}$time.formatted.{'formatstring'}{{/code}} 920 -* {{code language="xml"}}$time.formatted.default{{/code}} 936 +* {{code language="xml"}}$time.formatted.default{{/code}}(using default format string '%T') 921 921 922 922 In scripts, money is stored in cents, not Credits. The formatted representation always shows the value in Credits, including thousands separators. 923 923 ... ... @@ -951,10 +951,10 @@ 951 951 952 952 Examples: 953 953 954 -* {{code language="xml"}}(151s).formatted.{'%T'}{{/code}} 955 -* {{code language="xml"}}(151s).formatted.default{{/code}} 956 -* {{code language="xml"}}(151s).formatted.{'%.3T'}{{/code}} 957 -* {{code language="xml"}}(151s).formatted.{'%h:%M'}{{/code}} 970 +* {{code language="xml"}}(151s).formatted.{'%T'}{{/code}}⟹ {{code language="xml"}}'00:02:31'{{/code}} 971 +* {{code language="xml"}}(151s).formatted.default{{/code}}⟹ {{code language="xml"}}'00:02:31'{{/code}} (same as {'%T'}) 972 +* {{code language="xml"}}(151s).formatted.{'%.3T'}{{/code}}⟹ {{code language="xml"}}'00:02:31.000'{{/code}} 973 +* {{code language="xml"}}(151s).formatted.{'%h:%M'}{{/code}}⟹ {{code language="xml"}}'0:02'{{/code}} 958 958 959 959 === Complete property documentation === 960 960 ... ... @@ -966,7 +966,7 @@ 966 966 scriptproperties.html has to load files from different folders, which modern browsers do not allow by default for security reasons. In order to open scriptproperties.html, the following is required: 967 967 968 968 * Firefox: On the about:config page, the value of "security.fileuri.strict_origin_policy" has to be changed to "false". 969 -* Chrome: The Chrome launcher has to be started with the command-line parameter --allow-file-access-from-files --985 +* Chrome: The Chrome launcher has to be started with the command-line parameter --~-~---allow-file-access-from-files 970 970 {{/info}} 971 971 972 972 This provides you with a complete list of all supported "base keywords" and properties. To filter in this list, you can enter an expression in the text field: ... ... @@ -991,6 +991,31 @@ 991 991 992 992 * MD scripts and cues are identified by their names. So a script can only be refreshed if it has the same script name as before (file name is irrelevant). 993 993 * If there are new script files or new cue nodes (i.e. scripts/cues with new names) they are created and added properly. If you remove script files or cue nodes, the corresponding scripts/cues are removed from the game, including instances. 1010 +** (!) Pitfall: Cue Removal 1011 +If you remove a cue and then later add another cue with the same name, old save files will not know that the cue has been removed inbetween. In the following example the first cue was created setting $val_1 and the game is saved. 1012 +{{code language="xml"}}<cue name="Deprecated_Test1"> 1013 + <actions> 1014 + <set_value name="$val_1" exact="'old value'"/> 1015 + <debug_text text="$val_1"/> 1016 + </actions> 1017 +</cue>{{/code}} 1018 +\\If the Cue is deleted and years later a new cue with the same name appears, the old save will consider the new cue as already completed without executing its actions. The Cue PrintValue will fail to find a variable set up in its parent. 1019 +{{code language="xml"}}<cue name="Deprecated_Test1"> 1020 + <actions> 1021 + <set_value name="$val_2" exact="'new value'"/> 1022 + <debug_text text="$val_2"/> 1023 + </actions> 1024 + <cues> 1025 + <cue name="PrintValue"> 1026 + <actions> 1027 + <debug_text text="$val_2"/> 1028 + </actions> 1029 + </cue> 1030 + </cues> 1031 +</cue>{{/code}} 1032 +\\To avoid this, do not delete any cues (once they are public for save game compatibility), but empty them out and mark them as deprecated. This will prevent new cues with the same name in the script. 1033 +{{code language="xml"}}<!-- Deprecated Cues, kept to not duplicate names in future cues --> 1034 +<cue name="Deprecated_Test1" comment="deprecated"></cue>{{/code}} 994 994 * As a consequence, you CANNOT rename scripts or cues if you want to refresh them. Doing so would remove the old script or cue and add a new one with the new name. 995 995 * You CANNOT change a <cue> to a <library> or vice versa. 996 996 * You CANNOT add, remove, or change the "ref" attribute of a cue. But it is possible to remove the whole cue. (If all references to a library are removed you can also remove the library itself.)