Effectdata.plist

effectdata.plist is used to define visual effects. Visual effects are made up of models with materials and shaders and/or flashers, and have the same appearance as a normal ship. However, they are completely immaterial and cannot collide with or interact with other entities in any way. They also have no AI, and so must always be explicitly positioned and oriented by script.

Many of the keys have the same name as a key in shipdata.plist, and behave in the same way.

Effect keys

beacon

The beacon code of the effect - the first letter is what's displayed in the advanced space compass.

Identical in behaviour to the property of the same name in shipdata.plist

is_break_pattern

If this key is set to yes, the effect is a replacement or supplementary break pattern. Normally the display of all objects except the break pattern is suppressed on launch, but if this is set to yes, then the object will be displayed as normal. The display of the object outside of the break pattern sequence will be unaffected.

This can be combined with the ability to disable the standard break pattern through script to create an entirely new break pattern effect.

is_external_dependency

This key should be added to effects that use like_effect references to effects in other OXPs but don't depend on them. Normally Oolite will write errors in the log when it can't resolve a like_effect reference. When this key is set to YES, it will suppress the error generation.
This is probably only useful for visual effects which use models from other OXPs.

Example:

"is_external_dependency" = yes;

is_template

Set this to yes for effects which are only used through like_effect and are not intended to be used directly.

Example:

"is_template" = yes;

like_effect

Allows an effectdata entry (of an effect with many matching characteristics to another) to be short and sweet. With like_effect you can reference to another existing effectdata entry, and then only specify the differences to the 'original'. It takes the unique entry-identifier as argument. Of course you have to make sure that the 'original' you are referring to actually exists, or Oolite won't be able to create your visual effect.

Works well together with the is_template-key.

Example:

"my_effect" = {
  "like_effect" = "other_effect";
  "smooth" = "yes";
},

materials

See Materials in Oolite.

model

Assigns the effect's corresponding .dat file that will be found with the exact same name in the Models folder. Unlike ships, visual effects are not required to have a main model - they can consist solely of subentities if desired.

Example:

"model" = "example_effect.dat";

scanner_display_color1

Sets a scanner colour. If neither this nor scanner_display_color2 is set, the effect will be invisible on scanners.

Example:

"scanner_display_color1" = "greenColor";

scanner_display_color2

Sets a second scanner colour. If this is set, the effect will flash between the two colours.

Example:

"scanner_display_color2" = "redColor";

script

Specifies a JavaScript script to attach to the effect. Effect scripts only have a few event handlers but provide a convenient place to store timers and frame callbacks associated with the effect.

script_info

A property list whose contents are available to JavaScript scripts, for whatever use they desire. It is exposed to JavaScript as the scriptInfo property of VisualEffect objects.

Take note that when using an ascii plist, the JS engine will read in all entries as strings. When you need an entry as number, you might need to explicitly convert it to a number. This is specially true for booleans as a "NO" string will be read as true. For all normal keys it is Oolite that does the conversion for you.

shaders

The shaders dictionary has the same structure as the materials dictionary. When shaders are available, the contents of the shaders dictionary are used in preference to those in materials. If shaders are not available, the shaders dictionary is ignored.

smooth

Determines if the model will use glLightModel(GL_FLAT) or glLightModel(GL_SMOOTH).

If true, then lighting effects will be interpolated across the polygons of the model, giving a more 'rounded' effect.

Example:

"smooth" = yes;

subentities

An array of subentity definitions. Equivalent in format to the array in shipdata.plist except that neither ball turrets nor docks may be created. Both old-style and new-style subentity definitions are supported.

---