A GUIDE TO DECLARATIONS

- WHAT IS A DECLARATION?

A declaration is a key-value dictionary. It specifies parameters for an effect.
The particular set of parameters it can include depends on the effect. Refer to
the other files in this directory for examples.

- HOW DO DECLARATIONS WORK?

Declarations defined here are loaded when the game starts. They are stored in
a table under the name you give them:

<declaration>
<name>my_first_decl</name>
</declaration>

A declaration can inherit from another declaration, which means it will include
the keys defined in the inherited declaration in addition to its own (and so on
transitively up to a limit of about 64 ancestors).

To inherit from another declaration, use an <inherit> directive:

<declaration>
<name>my_second_decl</name>
<inherit>my_first_decl</inherit>
</declaration>

Any number of <inherit> directives are allowed.

- HOW DO I SPECIFY WHAT KIND OF EFFECT A DECLARATION CREATES?

Inherit from one of the built-in effect names, like "flare_trail_thruster" or
"nebula". Or inherit from another declaration that does. Note, however, that a
declaration need not inherit from anything. It can be used simply to specify a
set of common parameters to mix into other effects via inheritance.

- WHAT ORDER SHOULD DECLARATIONS BE SPECIFIED IN?

It doesn't matter. Inheritance works dynamically. A declaration is expanded when
it is used.

A declaration defined in the server XML can inherit from a declaration defined
in these files without problems. The opposite is also possible: a local
declaration can inherit from one defined on the server. However, the local
declaration will be unexpandable until the client receives its ancestors from
the server and stores them in the declaration table.

- HOW ARE DECLARATIONS TURNED INTO EFFECTS?

Declarations are embedded in space objects, visages and items in the server
XML. When the game sends an object to the client, any attached declarations are
transmitted in a compact form. When the client creates an effect, it looks for a
declaration attached to the subject of the effect.

For example, when the client needs to create a ship thruster, it looks for a
declaration attached to the ship's active engine item and uses it to configure
the particle system.

Environmental effects are created using "environmental" named visages. In this
case the client looks for a declaration attached to the visage to select and
configure the effect.

- HOW DO I USE CLIENT-SIDE DECLARATIONS FROM THE SERVER?

By inheriting them. For example (in the server XML):

<EFFECTDECL TYPE="thruster">
<INHERIT>my_locally_defined_thruster</INHERIT>
</EFFECTDECL>

Since server decls are sent over the network, it is prudent to define large
decls on the client and inherit them in this way, perhaps overriding a few
fields to customize colours or sizes.

- SHOULD I NAME MY DECLARATIONS USING NONSENSICAL ABBREVIATIONS, MIXED CASE,
SPACES AND/OR HUNGARIAN NOTATION?

No. This upsets the declaration hamster.

(`-`;-"```"-;`-`)
\.' KILL './
/ \
; 0 0 ;
/| = = |\
; \ '._Y_.' / ;
; `-._ \|/ _.-' ;
; `"""` ;
; `""-. .-""` ;
/; '--._ \ / _.-- ;\
: `. `/|| ||\` .' :
'. '-._ _.-' .'
(((-'` `"""""` `'-)))

Old.

SO IS YOUR FACE

C2 seer mechanics, because they can and it looks cool