Oolite JavaScript Reference: VisualEffect

From Elite Wiki
Revision as of 10:38, 19 September 2023 by Phkb (talk | contribs) (beaconCode)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

Prototype: Entity

The VisualEffect class is an Entity representing a visible but non-solid object defined from effectdata.plist. It has all the properties and methods of an Entity, and several others.


Unless otherwise stated This property was added in Oolite test release 1.77.


beaconCode : String (read/write)

If the effect is a beacon, an identifying string. The first character is used for identification on the Advanced Space Compass. For non-beacons, this property is null.


This property was added in Oolite test release 1.79.

beaconLabel : String (read/write)

A full label for the beacon. This is useful where the beacon code and the full beacon label do not begin with the same letter.


dataKey : String (read-only)

The data key from effectdata.plist used to generate this visual effect.


hullHeatLevel : Float (read/write)

While visual effects do not have a temperature as such, this property is provided to allow easy compatibility with the default Oolite shader for ships.


isBreakPattern : Boolean (read/write)

If this is true, the VisualEffect object will remain visible while break patterns on docking, launching or witchspace are being displayed (or not displayed). Normally all objects other than the break pattern itself are hidden.

scaleX, scaleY, scaleZ

scaleX : positive Float (read/write)
scaleY : positive Float (read/write)
scaleZ : positive Float (read/write)

Adjust the apparent size of the visual effect along each of its main axes. Subentity visual effects will be repositioned and rescaled accordingly. Subentity flashers will be repositioned and resized to keep a roughly proportionate volume, but not rescaled (as flashers are always spherical).

effect.scaleX = effect.scaleY = effect.scaleZ = newsize;

is equivalent to


if you need to rescale the effect uniformly


scannerDisplayColor1 : Colour specifier (read/write)

The first of two colours used by the ship’s scanner “lollipop”. When read, this will always be an array of four numbers in the range 0..1 (representing red, green, blue and alpha components). Any colour specifier format may be assigned to it. Assigning null will restore the value from effectdata.plist.

If both this and scannerDisplayColor2 are set to null, and no value is set for either in effectdata.plist then the effect will not appear on scanners.

See also: scannerDisplayColor2


scannerDisplayColor2 : Colour specifier (read/write)

The second scanner colour. If both scannerDisplayColor1 and scannerDisplayColor2 are specified, the scanner lollipop will alternate between the two colours.

See also: scannerDisplayColor1


script : Script (read-only)

The effect’s script. See the "Effect Scripts" section below for more details.


scriptInfo : Object (read-only)

The contents of the script_info key in the effect’s effectdata.plist entry, if any. This may be any property list object, but the recommended approach is to use a dictionary whose keys have a unique prefix (such as you should be using for file names, ship names etc.). A property list dictionary is converted to a JavaScript object with properties corresponding to the dictionary’s keys. All other property list types used with Oolite have directly corresponding JavaScript types.
When using numeric values in the scriptInfo, the JS engine is not able to detect the type reliably on all systems, so you always must explicitly convert its content to a number by using parseInt(scriptInfo.myKey) or parseFloat(scriptInfo.myKey).


shaderFloat1 : Number (read/write)
shaderFloat2 : Number (read/write)
shaderInt1 : Number (read/write)
shaderInt2 : Number (read/write)
shaderVector1 : Vector (read/write)
shaderVector2 : Vector (read/write)

Since visual effects have very few intrinsic properties, some arbitrary parameters which may be bound as shader uniforms are provided.


subEntities : Array (read-only)

A list of those subentities which are also visual effects


This method was added in Oolite test release 1.77.


function getMaterials() : Object

getMaterials() returns the effect's current materials dictionary, or if none present an empty dictionary.

See also: setMaterials(), getShaders()


function getShaders() : Object

getShaders() returns the effect's current shaders dictionary, or if none present an empty dictionary.

See also: setShaders(), getMaterials()


function remove()

Immediately removes the effect from the universe.


function restoreSubEntities()

Restores all missing subentities. Returns the number of subentities restored.


function scale(factor : Number)

Multiplies the size of the visual effect by factor. Subentities will be rescaled as well, and moved further from the centre of the effect as appropriate. An error will occur if factor is less than or equal to zero.

Note that this method resizes relative to the objects original size, not its current size. scale(1) will therefore always return to the original size.


function setMaterials(materialDictionary : Object [, shaderDictionary : Object]) : Boolean

Set the materials of the effect’s model. This works exactly like the materials dictionary in effectdata.plist. The optional shaderDictionary argument overrides materialDictionary if shaders are active.


effect.setMaterials({"my_effect_diffuse.png": { diffuse_map: "my_effect_damaged_diffuse.png" }});

See also: setShaders(), getMaterials()


function setShaders(shaderDictionary : Object) : Boolean

Set the shader materials of the effect’s model. Equivalent to setMaterials() with the materialDictionary value set to the effect’s current material dictionary.

See also: setMaterials(), getShaders()

Effect Scripts

Visual Effects may have an effect script attached to them. These work in a similar way to ship scripts, but define different handlers and properties. As with ship scripts, there will be a separate independent copy of the script for each visual effect.

Effects scripts have one property, this.visualEffect, which is a reference to the visual effect this is a script for. They have the following event handlers.


The effectRemoved handler is called when the effect is removed from the universe, either by the remove method or automatically when the player leaves the system. This is a good place to clean up any frame callbacks or timers associated with this effect.

this.effectRemoved = function()
     // Your code here


The effectSpawned handler is called on the first update after the effect is added to the universe.

this.effectSpawned = function()
     // Your code here