...
When the ref attribute is provided, all other attributes (except for name) will be ignored and taken from the library cue instead. (By default a library creates its own namespace, as if namespace="static" were specified. See the section about namespaces.)
Notes:
- It is not possible to directly call a cue which is 'inside' the library from 'outside' of the library, but it is possible to signal the library ref itself (possibly with parameters) and have a sub-cue inside the library listen to the signal on the library ref (possibly checking the parameters).
- You can access variables in the library root but generally this should be avoided in favor of parameterizing the library!
- there are some cases where you do want to access these variables directly, for example for maintaining savegame compatibility when patching.
Also all sub-cues of the library will be created as sub-cues of the cue that uses it. They are defined in the library as <cue>, not as <library>. (Although you can define a library as a sub-cue of another library, the location in the file does not matter, as already stated above.) It is even possible to reference other libraries in sub-cues of a library!
...
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 attributedo 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:
- It is not possible to directly call a cue which is 'inside' the library from 'outside' of the library, but it is possible to signal the library ref itself (possibly with parameters) and have a sub-cue inside the library listen to the signal on the library ref (possibly checking the parameters).
- You can access variables in the library root but generally this should be avoided in favor of parameterizing the library!
- there are some cases where you do want to access these variables directly, for example for maintaining savegame compatibility when patching.
Library Parameters
A library can be parametrised, so that it can be adapted to the needs of a missions that uses it. You can define required and/or optional parameters for a library, and it will be validated at load time that the user of the library has provided all required parameters.
...
You can build expressions by combining sub-expressions with operators. For Boolean operations, expressions are considered “false” if they are equal to zero, “true” otherwise. The following operators, delimiters, and constants are supported:
Operator / Delimiter / Constant | Type | Example | Result of example | Description |
|---|---|---|---|---|
null | constant |
|
| Null value, see above |
false | constant |
|
| Integer value 0, useful in Boolean expressions |
true | constant |
|
| Integer value 1, useful in Boolean expressions |
pi | constant |
|
| π as an angle (same as 180deg) |
() | delimiter |
|
| Parentheses for arithmetic grouping |
[] | delimiter |
|
| List of values |
| table[] | delimiter | table[$foo='bar', {1+1}=40+2] | table[$foo='bar', {2}=42] | Table of values |
{} | delimiter |
|
| Text lookup (page ID and text ID) from TextDB |
+ | unary |
|
| Denotes positive number (no effect) |
- | unary |
|
| Negates the following number |
not | unary |
|
| Yields true if the following expression is false (equal to zero), false otherwise |
typeof | unary |
|
| Yields the data type of the following sub-expression |
sin | unary |
|
| Sine (function-style, parentheses required) |
cos | unary |
|
| Cosine (function-style, parentheses required) |
sqrt | unary |
|
| Square root (function-style, parentheses required) |
exp | unary |
|
| Exponential function (function-style, parentheses required) |
log | unary |
|
|
|
Natural logarithm (function-style, parentheses required) |
| abs | unary |
|
exp(1)
2.71828LF
| 42 | Absolute value (function-style, parentheses required) (added in X4 v6.00) |
| sgn | unary |
sgn( |
3.0LF
-42) | -1 | Sign function (function-style, parentheses required) (added in X4 v6.00) | ||
^ | binary |
|
| Power |
* | binary |
|
| Multiplication |
/ | binary |
|
| Division |
% | binary |
|
| Modulus (remainder of integer division) |
+ | binary |
|
| Addition String concatenation |
- | binary |
|
| Subtraction |
lt < (<) | binary |
|
| Less than |
le <= | binary |
|
| Less than or equal to |
gt > (>) | binary |
|
| Greater than |
ge >= | binary |
|
| Greater than or equal to |
== | binary |
|
| Equal to |
!= | binary |
|
| Not equal to |
and | binary |
|
| Logical AND (short-circuit semantics) |
or | binary |
|
| Logical OR (short-circuit semantics) |
if ... then ... if ... then ... else ... | ternary |
|
| Conditional operator ("inline if") |
Operator precedence rules
...
You can access many player-related game properties via the keyword “player”, for example:
player.name: The player’s name
player.age: The passed in-game time since game start
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 (X Rebirth only): The player's own ship (but the player is not necessarily on board)
- player.occupiedship (X4 only): The ship that the player is currently piloting, or null if the player is not piloting
- player.entity: The actual player object
player.zone, player.sector, player.cluster, player.galaxy: Location of the player entity
player.copilot (X Rebirth only): The co-pilot NPC
The game consists of objects of different classes (zones, ships, stations, NPCs). They have the common datatype "component", however, they have different properties, e.g. NPCs have the property "race", but ships don't.
...