OXPConfig Doc

From Elite Wiki
Revision as of 15:15, 2 February 2013 by Svengali (talk | contribs) (→‎How to join)

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 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!!!).


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 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. See oxpcSettings.

Parameters

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

Returns

nothing.


changeOXPData()

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 .Notify flag or changing the .Hide flag (see oxpcSettings). 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. See oxpcSettings.

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

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 OXPConfigs .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. 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 Optional, defaults to false. If this flag is used, please keep in mind that this will raise the processing-time of OXPConfig. See oxpcNotifyOnChange().
Info.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, defaults to false. See oxpcNotifyOnChange().
Info.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, 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).
Bool0.Hide
Boolean. Optional. If true OXPConfig does not expose this property to the user.


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).
SInt0.Hide
Boolean. Optional. If true OXPConfig does not expose this property to the user.


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).
EInt0.Hide
Boolean. Optional. If true OXPConfig does not expose this property to the user.


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 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

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