OXPConfig Doc

From Elite Wiki
Mr Gimlet.png

Please note:   The documentation reflects the state up to v2.3.2. A coming version 3 is currently prepared by Lone_Wolf..

Overview

OXPConfig is more or less only a Interface to give OXPs the possibility to let users change, load and store settings in the game. It does it only for OXPs which are including the necessary data (and if the OXP is in the database for performance reasons). This way it's still up to the OXPers to decide if they want user settings or not. In most cases it's really easy to implement the data and usually only needs a few lines of code.

OXPConfig looks up all worldScripts which are in it's database for the .oxpcSettings object, collects it, deletes it if the .LeaveData flag is not set and applies stored settings to these OXPs. It 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. OXPs can also be notified about changes via the .Notify and .DynamicNotify flag.

Sometimes you'll find posts that OXPConfig is a Debug-Tool or a tool for OXP-Developers only. This is not really right. It is a Interface between Player and OXPs and completely relies on the provided settings in the OXPs. They can use it to control their own debug features though (e.g. logging or measuring functions, etc.), but this is up to the OXPs. OXPConfig supports OXPers and Players though in case of trouble as it can write missionVariables and worldScript properties to Latest.log to help identifying the culprit.

As OXPConfig is a OXP all rules for OXPs in Oolite apply (inclusive the dynamic loading order and timelimiter!!!).


Missionscreens in OXPConfig.js are using the screenID Added in v2.3.2

"OXPConfig"


How to join

If any of your worldScripts should be included in the database send a pm with infos to Lone_Wolf or post your request in the OXPConfig thread:

  • name of worldScript
  • display name, can be different from the scriptname.


The script will get an ID (stored in OXPConfig) that is internally used to relate saved settings to specific OXPs.


A test OXP is available to demonstrate usage of .Hide and .DynamicNotify flags:


Properties

The listed properties are useful for OXP-Developers. Players shouldn't need to change the defaults.

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). It's main purpose is to check if the settings are correctly identified - loading and saving is disabled for OXPs which are not in the database. Default is false.

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. It's main purpose is to check if the settings are correctly identified - loading and saving is disabled for OXPs which are not in the database. Default is false.

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. Default is false.

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

oxpcNotifyOnChange()

this.oxpcNotifyOnChange = function(n)

The callback is sent if .Notify is set and stored settings are loaded, default settings are loaded by the user, the player exits OXPConfig or switches to the OXP list. It is also sent if .DynamicNotify is set whenever the user changes settings through OXPConfigs interface.

Parameters

n
Number. 1 - boolean settings changed, 2 - short unsigned integers changed, 4 - unsigned 24Bit integer changed.
Will always be 7 when OXPConfig loads stored settings or default settings are loaded if .Notify is true.
Will be 1, 2 or 4 if user changes settings and .DynamicNotify is true based on the type of the changed setting.
Will be the sum of changed types (1...7) if the user has finished his changes and leaves the screens if .Notify is true.

Returns

nothing.


changeOXPData()

this.changeOXPData = function(obj)

OXPConfig can be forced to rebuild its internal searchtree with changed settings for a specified OXP. This is only meaningful for OXPs which need to change their settings e.g. by adding the .Notify flag or changing the .Hide flag. Usually there's no need to call it though - OXPConfig stores a reference to the .oxpcSettings object and the recommended way is to use the .LeaveData flag to keep the reference alive.

Paramerters

obj
Object.

Returns

success
Boolean. True if successful, otherwise false.


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 wrapper object holds the settings for an OXP. The object must be placed in the scripts body. OXPConfig deletes this object after gathering the infos if .LeaveData flag is not true. Make sure the object is extensible and not sealed or frozen, otherwise it will be rejected.

Overview about the objects members:

Info

Object with members. Required. General infos about an OXP and flags for OXPConfig.

Name
String. Name of the worldScript.
Required.
MinVersion
String. Minimum version.
Optional. Default “0.0”.
Display
String. Name that should be displayed.
Optional. Default .Name.
EarlyCall
Boolean. Flag if .startUp should be called by OXPConfig. If this flag is used it is strongly recommended to use the schemata PhantorGorth has developed. But keep in mind that this will raise the time OXPConfigs .startUp takes.
Optional. Defaults false.
EarlySet
Boolean. Flag if settings should be applied in OXPConfigs .startUp or later. If this flag is used, please keep in mind that this will raise the time OXPConfigs .startUp takes. This is not a big problem as Oolite uses a 5 seconds limit for .startUp functions.
Optional. Default false.
Notify
Boolean. Flag if OXP should be notified about applied or changed settings. The notification is sent if stored settings are loaded, default settings are loaded by the user, the player exits OXPConfig or switches to the OXP list. If this flag is used, please keep in mind that this will raise the processing-time of OXPConfig.
Optional. Default false.
DynamicNotify
Boolean. Flag if OXP should be notified about every change of settings by the user. Useful for updating of descriptions based on current settings.
Optional. Default false.
LeaveData
Boolean. Flag if OXPConfig should not delete .oxpcSettings after gathering the infos. Setting this flag is recommended for OXPs which are changing their settings (e.g. descriptions or .Hide flags) to keep the reference alive.
Optional. Default false.
InfoB
String. Additional text for the boolean screen. Max 240 chars.
Optional. Default "not available".
InfoS
String. Additional text for the short unsigned integer screen. Max 240 chars.
Optional. Default "not available".
InfoE
String. Additional infos for the unsigned 24Bit integer screen. Max 240 chars.
Optional. Default "not available".


Bool..

Object with members. Infos and settings for a boolean property. Possible are Bool0...Bool3.

Name
String. Name of the property. E.g. if the script declares this.logging, Name would be “logging”.
Required.
Def
Boolean. Default value of the property. This is used to reset settings when user chooses to load defaults.
Required.
Desc
String. Short description. OXPConfig truncates overlengthie descriptions (~18 em).
Required.
Hide
Boolean. If true OXPConfig does not expose this property to the user.
Optional. Default false.


SInt..

Object with members. Infos and settings for a short unsigned integer property. Possible are SInt0...SInt3.

Name
String. Name of the property. E.g. if the script declares this.maxMoons, Name would be “maxMoons”.
Required.
Def
Number. Default value of the property. This is used to reset settings when user chooses to load defaults.
Required.
Max
Number. Maximum value of the property.
Required.
Desc
String. Short description. OXPConfig truncates overlengthie descriptions (~9 em).
Required.
Hide
Boolean. If true OXPConfig does not expose this property to the user.
Optional. Default false.


EInt0

Object with members. Infos and settings for the unsigned 24Bit integer property.

Name
String. Name of the property. E.g. if the script declares this.myShips, Name would be “myShips”.
Required.
Def
Number. Default value of the property. This is used to reset settings when user chooses to load defaults.
Required.
Max
Number. Maximum value of the property.
Required.
Desc
Array. Short descriptions for every bit. OXPConfig truncates overlengthie descriptions (~8 em).
Required.
Hide
Boolean. If true OXPConfig does not expose this property to the user.
Optional. Default false.


oxpcSettings example

Example declaration: 

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

Other checked properties

deactivated

OXPConfig checks a boolean property (.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 .genericUserColors. 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 gets 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


Links

Further readings:

Retrieved from "http://backup.witchspacewiki.org/index.php?title=OXPConfig_Doc&oldid=47577"