OXPConfig Doc

Overview

OXPConfig is the script for configuring OXPs. OXPConfig runs in two cycles when Oolite gets started or a savedgame is loaded and the flags in OXPs can specify when settings should be applied. The reason is that startUp can be pretty timecostly, specially when OXPs have to be configured as early as possible and if dependency chains are involved. For OXPs which don’t need early settings OXPConfig applies them on guiScreenChanged, alertConditionChanged or triggered by the timer. If a OXP sets the Notify flag OXPConfig tries to pass a integer to the changed OXP.

Callback

	worldScripts[oxpcSettings.Info.Name].oxpcNotifyOnChange(what);

Properties

collectAll

Boolean. En/disables collecting of data from all worldScripts. This can be pretty slow if hundreds of OXPs are installed and in combination with logging enabled it can lead to aborting by Oolites timelimiter in trunk (even if I haven’t seen it yet).

displayAll

Boolean. En/disables collecting data from all OXPs which are declaring oxpcSettings. If false OXPConfig will only check OXPs which are in it’s internal database and removes entries which are not declaring the necessary settings.

logEarly

Boolean. En/disables the logging of OXPs which have set the EarlyCall flag. If OXPConfig calls the startUp it will log this event. Additionally this switch is for measuring the time OXPConfig needs for it’s own startUp, including collecting data from all OXPs, calling the startUp’s, building it’s search trees and applying settings. The time is quantised in units of maybe 50/60ms or 16 ms or 10ms or ..., depending on system.

logging

Boolean. Switches extended logging on/off and can be configured. This is quite verbose and slows down the whole processing and it’s primary goal is to give developers insight in the internal ongoings and to locate problems. Default is false.

Functions

oxpcLookup()

	this.oxpcLookup = function()

This function is called by OXPConfig to establish the oxpcSettings. The way is explicitely choosen to overcome the loading order of scripts in Oolite. OXPConfig calls this function on it’s own.

Parameters

none.

Returns

nothing.

oxpcNotifyOnChange()

	this.oxpcNotifyOnChange = function(n)

This function is called by OXPConfig when settings are changed and the flag for notifications is set.

Parameters

n

Number. 1 - boolean settings changed, 2 - short unsigned integers changed, 4 - unsigned 24Bit integer changed.

Returns

nothing.

startUp()

	this.startUp = function()

This function is called by Oolite when the application gets started or a savegame was loaded and starts OXPConfigs own handling. Changes to OXPConfigs displayAll and collectAll require a restart to take effect. All switches are false by default. The integer settings are only there as examples and have no real function for OXPConfig itself.

OXPConfig uses two missionVariables

• missionVariables.OXPConfig_Self - used to store OXPConfigs setup.
• missionVariables.OXPConfig_Change - used to store OXP settings.

Parameters

none.

Returns

nothing.

Objects

oxpcSettings

This object holds the settings for an OXP. OXPConfig deletes this object after gathering the infos if oxpcSettings.Info.LeaveData flag is not specified.

oxpcSettings

Info

Object. General infos about an OXP and flags for OXPConfig and is required:

Info.Name

String. Name of the worldScript. Required.

Info.MinVersion

String. Minimum version. Optional, defaults to “0.0”.

Info.Display

String. Name that should be displayed. Optional, defaults to oxpcSettings.Info.Name.

Info.EarlyCall

Boolean. Flag if startUp should be called by OXPConfig. Optional, defaults to false. If this flag should be used it is strongly recommended to use the schemata PhantorGorth has developed. See Handling_OXP_Dependencies_with_JavaScript. But keep in mind that this will raise the time OXPConfigs startUp takes.

Info.EarlySet

Boolean. Flag if settings should be applied in OXPConfig startUp or later. Optional, defaults to false. If this flag is used, please keep in mind that this will raise the time OXPConfigs startUp takes.

Info.Notify

Boolean. Flag if OXP should be notified about applied or changed settings. Optional, defaults to false. If this flag is used, please keep in mind that this will raise the processing-time of OXPConfig.

Info.LeaveData

Boolean. Flag if OXPConfig should not delete oxpcSettings after gathering the infos. Optional, defaults to false.

Info.InfoB

String. Additional text for the boolean screen. Max 240 chars.

Info.InfoS

String. Additional text for the short unsigned integer screen. Max 240 chars.

Info.InfoE

String. Additional infos for the unsigned 24Bit integer screen. Max 240 chars.

Bool0

Object. Infos and settings for a boolean property. Possible are Bool0...Bool3. If used the following settings are required:

Bool0.Name

String. Name of the property. E.g. if the script declares this.logging, Name would be “logging”.

Bool0.Def

Boolean. Default value of the property. This is used to reset settings when user chooses to load defaults.

Bool0.Desc

String. Short description. OXPConfig truncates overlengthie descriptions (~18 em).

SInt0

Object. Infos and settings for a short unsigned integer property. Possible are SInt0...SInt3. If used the following settings are required:

SInt0.Name

String. Name of the property. E.g. if the script declares this.maxMoons, Name would be “maxMoons”.

SInt0.Def

Number. Default value of the property. This is used to reset settings when user chooses to load defaults.

SInt0.Max

Number. Maximum value of the property.

SInt0.Desc

String. Short description. OXPConfig truncates overlengthie descriptions (~9 em).

EInt0

Object. Infos and settings for the unsigned 24Bit integer property. If used the following settings are required:

EInt0.Name

String. Name of the property. E.g. if the script declares this.myShips, Name would be “myShips”.

EInt0.Def

Number. Default value of the property. This is used to reset settings when user chooses to load defaults.

EInt0.Max

Number. Maximum value of the property.

EInt0.Desc

Array. Short descriptions for every bit. OXPConfig truncates overlengthie descriptions (~8 em).

Example declaration:

	this.oxpcLookup = function(){ this.oxpcSettings = { Info: {Name:"myOXP", Notify:true, InfoB:"Funny things can be configured.", InfoS:"Chance."}, Bool0: {Name:"logging", Def:false, Desc:"Logging functions."}, SInt0: {Name:"sliderA", Def:0x2, Max:0xa, Desc:"Chance."} } }

Starting with OXPConfig2.0.3 a simplified way is possible by placing the settings in the script body:

	this.oxpcSettings = { Info: {Name:"myOXP", Notify:true, InfoB:"Funny things can be configured.", InfoS:"Chance."}, Bool0: {Name:"logging", Def:false, Desc:"Logging functions."}, SInt0: {Name:"sliderA", Def:0x2, Max:0xa, Desc:"Chance."} }

Other checked properties

deactivated

OXPConfig checks a boolean property (this.deactivated) in OXPs. If set to true the handling for this OXP is switched off. Reason is that a script can delete itself (e.g. if it has already done its job and there's no need for it anymore) to free ressources. The flag simply indicates this. OXPConfig checks this flag on every activation.

Specials

User defined colors

Starting with 2.0.8 OXPConfig ships a feature to set 20 colors for scanner colors in supporting OXPs.

It declares a array with 20 elements in the format [ [[c0-color1],[c0-color2]], ... ] and a missionVariable. OXPs can get a instance of this array

	this.myColors = worldScripts.OXPConfig.genericUserColors;

A simple example could look like:

this.startUp = function(){ this.myColor = "grayColor","greenColor"; if(worldScripts.OXPConfig) this.grabArrayDelayed = true; else if(missionVariables.genericUserColors) this.myColor = JSON.parse(missionVariables.genericUserColors); }; this.shipWillLaunchFromStation = function() { if(this.grabArrayDelayed){ this.myColor = worldScripts.OXPConfig.genericUserColors; delete this.grabArrayDelayed; } }; this.shipTargetAcquired = function(newTarget) { if(!newTarget) return; newTarget.scannerDisplayColor1 = this.myColor[0][0]; newTarget.scannerDisplayColor2 = this.myColor[0][1]; };

The example defines a default array which is used if neither array, nor the related mV is available. Then it checks if OXPConfig is installed - if so it delays the access (here shipWillLaunchFromStation) to avoid loading order stuff without the need of a timer and grabs the reference. If a user changes the settings through OXPConfigs GUI the references will be automagically updated as well without any callback/registering or constant checking (associative array). If no OXPConfig is installed (= array unavailable), it tries to get the data from the mV.

OXPConfig itself does a similiar thing. The default array get defined in the script body. On startUp it tries to read in the mV. If not available the mV gets created. If OXPConfig shuts down this property is not deleted (unlike most other properties) to stay available for other OXPs. The mV gets updated on leaving the color settings.

List of color supporting OXPs

- none

---