Difference between revisions of "OXPConfig Doc"

From Elite Wiki
m
m (added note about v3)
(8 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 +
{{OXPNote|The documentation reflects the state up to v2.3.2. A coming version 3 is currently prepared by Lone_Wolf.}}
 +
 
== Overview ==
 
== 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]] 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 a specific object, collects this data 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 <tt>.startUp</tt> 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 <tt>guiScreenChanged</tt>, <tt>alertConditionChanged</tt> or triggered by the timer. OXPs can also be notified about changes via the <tt>.Notify</tt> flag.  
+
OXPConfig looks up all worldScripts which are in it's database for the <tt>.oxpcSettings</tt> object, collects it, deletes it if the <tt>.LeaveData</tt> 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 <tt>.startUp</tt> 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 <tt>guiScreenChanged</tt>, <tt>alertConditionChanged</tt> or triggered by the timer. OXPs can also be notified about changes via the <tt>.Notify</tt> and <tt>.DynamicNotify</tt> 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.
 
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.
Line 9: Line 11:
  
 
* List of supported [[:Category:OXPConfig-compatible OXPs|OXPConfig-compatible OXPs]] - currently {{PAGESINCATEGORY:OXPConfig-compatible OXPs}}.
 
* List of supported [[:Category:OXPConfig-compatible OXPs|OXPConfig-compatible OXPs]] - currently {{PAGESINCATEGORY:OXPConfig-compatible OXPs}}.
 +
 +
 +
Missionscreens in <tt>OXPConfig.js</tt> are using the screenID {{AV|2.3.2}}
 +
{{CodeEx|codeex="OXPConfig"}}
  
  
 
== How to join ==
 
== How to join ==
If any of your worldScripts should be included in the database send a pm with infos to Svengali or post your request in the [http://aegidian.org/bb/viewtopic.php?f=4&t=4908 OXPConfig] thread:
+
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 [http://aegidian.org/bb/viewtopic.php?f=4&t=4908 OXPConfig] thread:
 
* name of worldScript
 
* name of worldScript
 
* display name, can be different from the scriptname.
 
* display name, can be different from the scriptname.
Line 18: Line 24:
  
 
The script will get an ID (stored in OXPConfig) that is internally used to relate saved settings to specific OXPs.
 
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 <tt>.Hide</tt> and <tt>.DynamicNotify</tt> flags:
 +
* [https://www.box.com/s/6zcqt48f8dq5p86pdz67 OXPConfig_Test.zip] (1.49 KB)
  
  
Line 38: Line 48:
 
=== oxpcNotifyOnChange() ===
 
=== oxpcNotifyOnChange() ===
 
{{CodeEx|codeex=this.oxpcNotifyOnChange = function(n)}}
 
{{CodeEx|codeex=this.oxpcNotifyOnChange = function(n)}}
This function is called by OXPConfig when settings are changed and the flag for notifications is set. See [[#oxpcSettings|oxpcSettings]].
+
The callback is sent if <tt>.Notify</tt> 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 <tt>.DynamicNotify</tt> is set whenever the user changes settings through OXPConfigs interface.
 +
* See [[#oxpcSettings|oxpcSettings]].
  
 
'''Parameters'''
 
'''Parameters'''
 
:;n:Number. 1 - boolean settings changed, 2 - short unsigned integers changed, 4 - unsigned 24Bit integer changed.
 
:;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 <tt>.Notify</tt> is true.
 +
::Will be 1, 2 or 4 if user changes settings and <tt>.DynamicNotify</tt> 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 <tt>.Notify</tt> is true.
  
 
'''Returns'''
 
'''Returns'''
Line 49: Line 63:
 
=== changeOXPData() ===
 
=== changeOXPData() ===
 
{{CodeEx|codeex=this.changeOXPData = function(obj)}}
 
{{CodeEx|codeex=this.changeOXPData = function(obj)}}
OXPConfig can be forced to rebuild its internal searchtree. This is only meaningful for OXPs which need to change their settings e.g. by adding the <tt>.Notify</tt> flag or changing the <tt>.Hide</tt> flag (see [[#oxpcSettings|oxpcSettings]]). Usually there's no need to call it though - OXPConfig stores a reference to the <tt>.oxpcSettings</tt> object and the recommended way is to use the <tt>.LeaveData</tt> flag to keep the reference alive.
+
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 <tt>.Notify</tt> flag or changing the <tt>.Hide</tt> flag. Usually there's no need to call it though - OXPConfig stores a reference to the <tt>.oxpcSettings</tt> object and the recommended way is to use the <tt>.LeaveData</tt> flag to keep the reference alive.
 +
* See [[#oxpcSettings|oxpcSettings]].
  
 
'''Paramerters'''
 
'''Paramerters'''
:;obj:Object. See [[#oxpcSettings|oxpcSettings]].
+
:;obj:Object.
  
 
'''Returns'''
 
'''Returns'''
Line 60: Line 75:
 
=== startUp() ===
 
=== startUp() ===
 
{{CodeEx|codeex=this.startUp = function()}}
 
{{CodeEx|codeex=this.startUp = function()}}
This function is called by Oolite when the application gets started or a savegame was loaded and starts OXPConfigs own handling.
+
This function is called by Oolite when the application gets started or a savegame was loaded and starts OXPConfigs own handling. Changes to OXPConfigs <tt>.displayAll</tt> and <tt>.collectAll</tt> 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.
Changes to OXPConfigs <tt>.displayAll</tt> and <tt>.collectAll</tt> 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
+
OXPConfig uses two missionVariables
  
 
* missionVariables.OXPConfig_Self - used to store OXPConfigs setup.
 
* missionVariables.OXPConfig_Self - used to store OXPConfigs setup.
Line 77: Line 91:
 
== Objects ==
 
== Objects ==
 
=== oxpcSettings ===
 
=== oxpcSettings ===
This object holds the settings for an OXP. OXPConfig deletes this object after gathering the infos if <tt>oxpcSettings.Info.LeaveData</tt> flag is not true. Make sure the object is extensible and not sealed or frozen, otherwise it will be rejected.
+
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 <tt>.LeaveData</tt> flag is not true. Make sure the object is extensible and not sealed or frozen, otherwise it will be rejected.
  
'''oxpcSettings'''
+
Overview about the objects members:
:;Info:Object. General infos about an OXP and flags for OXPConfig and is required:
+
==== Info ====
:;Info.Name:String. Name of the worldScript. Required.
+
Object with members. Required. General infos about an OXP and flags for OXPConfig.
:;Info.MinVersion:String. Minimum version. Optional, defaults to “0.0”.
+
:;Name:String. Name of the worldScript.
:;Info.Display:String. Name that should be displayed. Optional, defaults to <tt>oxpcSettings.Info.Name</tt>.
+
::Required.
:;Info.EarlyCall:Boolean. Flag if <tt>.startUp</tt> 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 <tt>.startUp</tt> takes.
+
:;MinVersion:String. Minimum version.
:;Info.EarlySet:Boolean. Flag if settings should be applied in OXPConfigs <tt>.startUp</tt> or later.  Optional, defaults to false. If this flag is used, please keep in mind that this will raise the time OXPConfigs <tt>.startUp</tt> takes.
+
::Optional. Default “0.0”.
:;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. See [[#oxpcNotifyOnChange()|oxpcNotifyOnChange()]].
+
:;Display:String. Name that should be displayed.
:;Info.LeaveData:Boolean. Flag if OXPConfig should not delete <tt>.oxpcSettings</tt> after gathering the infos. Optional, defaults to false.
+
::Optional. Default <tt>.Name</tt>.
:;Info.InfoB:String. Additional text for the boolean screen. Max 240 chars.
+
:;EarlyCall:Boolean. Flag if <tt>.startUp</tt> 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 <tt>.startUp</tt> takes.
:;Info.InfoS:String. Additional text for the short unsigned integer screen. Max 240 chars.
+
::Optional. Defaults false.
:;Info.InfoE:String. Additional infos for the unsigned 24Bit integer screen. Max 240 chars.
+
::* See [[Handling_OXP_Dependencies_with_JavaScript]].
 +
:;EarlySet:Boolean. Flag if settings should be applied in OXPConfigs <tt>.startUp</tt> or later. If this flag is used, please keep in mind that this will raise the time OXPConfigs <tt>.startUp</tt> takes. This is not a big problem as Oolite uses a 5 seconds limit for <tt>.startUp</tt> 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.
 +
::* See [[#oxpcNotifyOnChange()|oxpcNotifyOnChange()]].
 +
:;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.
 +
::* See [[#oxpcNotifyOnChange()|oxpcNotifyOnChange()]].
 +
:;LeaveData:Boolean. Flag if OXPConfig should not delete <tt>.oxpcSettings</tt> after gathering the infos. Setting this flag is recommended for OXPs which are changing their settings (e.g. descriptions or <tt>.Hide</tt> 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".
  
  
:;Bool0:Object. Infos and settings for a boolean property. Possible are Bool0...Bool3. If used the following settings are required:
+
==== Bool.. ====
:;Bool0.Name:String. Name of the property. E.g. if the script declares this.logging, Name would be “logging”.
+
Object with members. Infos and settings for a boolean property. Possible are Bool0...Bool3.
:;Bool0.Def:Boolean. Default value of the property. This is used to reset settings when user chooses to load defaults.
+
:;Name:String. Name of the property. E.g. if the script declares this.logging, Name would be “logging”.
:;Bool0.Desc:String. Short description. OXPConfig truncates overlengthie descriptions (~18 em).
+
::Required.
:;Bool0.Hide:Boolean. Optional. If true OXPConfig does not expose this property to the user.
+
:;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.
  
  
:;SInt0:Object. Infos and settings for a short unsigned integer property. Possible are SInt0...SInt3. If used the following settings are required:
+
==== SInt.. ====
:;SInt0.Name:String. Name of the property. E.g. if the script declares this.maxMoons, Name would be “maxMoons”.
+
Object with members. Infos and settings for a short unsigned integer property. Possible are SInt0...SInt3.
:;SInt0.Def:Number. Default value of the property. This is used to reset settings when user chooses to load defaults.
+
:;Name:String. Name of the property. E.g. if the script declares this.maxMoons, Name would be “maxMoons”.
:;SInt0.Max:Number. Maximum value of the property.
+
::Required.
:;SInt0.Desc:String. Short description. OXPConfig truncates overlengthie descriptions (~9 em).
+
:;Def:Number. Default value of the property. This is used to reset settings when user chooses to load defaults.
:;SInt0.Hide:Boolean. Optional. If true OXPConfig does not expose this property to the user.
+
::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. Infos and settings for the unsigned 24Bit integer property. If used the following settings are required:
+
==== EInt0 ====
:;EInt0.Name:String. Name of the property.  E.g. if the script declares this.myShips, Name would be “myShips”.
+
Object with members. Infos and settings for the unsigned 24Bit integer property.
:;EInt0.Def:Number. Default value of the property. This is used to reset settings when user chooses to load defaults.
+
:;Name:String. Name of the property.  E.g. if the script declares this.myShips, Name would be “myShips”.
:;EInt0.Max:Number. Maximum value of the property.
+
::Required.
:;EInt0.Desc:Array. Short descriptions for every bit. OXPConfig truncates overlengthie descriptions (~8 em).
+
:;Def:Number. Default value of the property. This is used to reset settings when user chooses to load defaults.
:;EInt0.Hide:Boolean. Optional. If true OXPConfig does not expose this property to the user.
+
::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:
 
Example declaration:
{{CodeEx|codeex=this.oxpcSettings = {
+
  this.oxpcSettings = {
:Info: {Name:"myOXP", Notify:true, InfoB:"Funny things can be configured.", InfoS:"Chance."},
+
    Info: {Name:"myOXP", Notify:true, InfoB:"Funny things can be configured.", InfoS:"Short explanation."},
:Bool0: {Name:"logging", Def:false, Desc:"Logging functions."},
+
    Bool0: {Name:"logging", Def:false, Desc:"Logging functions."},
:SInt0: {Name:"sliderA", Def:0x2, Max:0xa, Desc:"Chance."}
+
    SInt0: {Name:"sliderA", Def:0x2, Max:0xa, Desc:"Chance."},
}
+
    SInt1: {Name:"sliderB", Def:0x5, Max:0xff, Desc:"OptionB."}
}}
+
  };
 
 
  
 
== Other checked properties ==
 
== Other checked properties ==
Line 136: Line 182:
  
 
It declares a array with 20 elements in the format [ [[c0-color1],[c0-color2]], ... ] and a missionVariable <tt>.genericUserColors</tt>. OXPs can get a instance of this array
 
It declares a array with 20 elements in the format [ [[c0-color1],[c0-color2]], ... ] and a missionVariable <tt>.genericUserColors</tt>. OXPs can get a instance of this array
{{CodeEx|codeex=this.myColors = worldScripts.OXPConfig.genericUserColors;}}
+
  this.myColors = worldScripts.OXPConfig.genericUserColors;
  
 
A simple example could look like:
 
A simple example could look like:
{{CodeEx|codeex=this.startUp = function(){
+
  this.startUp = function(){
:this.myColor = [ ["grayColor","greenColor"] ];
+
    this.myColor = [ ["grayColor","greenColor"] ];
:if(worldScripts.OXPConfig) this.grabArrayDelayed = true;
+
    if(worldScripts.OXPConfig) this.grabArrayDelayed = true;
:else if(missionVariables.genericUserColors) this.myColor = JSON.parse(missionVariables.genericUserColors);
+
    else if(missionVariables.genericUserColors) this.myColor = JSON.parse(missionVariables.genericUserColors);
};
+
  };
 
+
  this.shipWillLaunchFromStation = function(){
this.shipWillLaunchFromStation = function()
+
    if(this.grabArrayDelayed){
{
+
      this.myColor = worldScripts.OXPConfig.genericUserColors;
:if(this.grabArrayDelayed){
+
      delete this.grabArrayDelayed;
::this.myColor = worldScripts.OXPConfig.genericUserColors;
+
    }
::delete this.grabArrayDelayed;
+
  };
:}
+
  this.shipTargetAcquired = function(newTarget){
};
+
    if(!newTarget) return;
 
+
    newTarget.scannerDisplayColor1 = this.myColor[0][0];
this.shipTargetAcquired = function(newTarget)
+
    newTarget.scannerDisplayColor2 = this.myColor[0][1];
{
+
  };
: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 <tt>.shipWillLaunchFromStation</tt>) 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.
 
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 <tt>.shipWillLaunchFromStation</tt>) 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 <tt>.startUp</tt> 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.
+
OXPConfig itself does a similiar thing. The default array gets defined in the script body. On <tt>.startUp</tt> 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 ===
 
=== List of color supporting OXPs ===
 
- none
 
- none
 +
 +
 +
== Links ==
 +
Further readings:
 +
* [[Handling_OXP_Dependencies_with_JavaScript]] - explanation by PhantorGorth.
 +
* [[Javascript_Operators]] - quick introduction in operators.
 +
* [[Variables_in_Oolite_JavaScripts]] - quick introduction in using variables.
 +
* ... - infos about loading order, access to missionVariables, order of fired handlers, Oolites timelimiter and profiling via console.
  
 
----
 
----
 
[[Category:OXPDoc]]
 
[[Category:OXPDoc]]

Revision as of 15:12, 26 May 2015

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: