Lib Config 101 - Revision history

Phkb: /* 1. Dataset */

2026-05-24T10:20:28Z

‎1. Dataset

Phkb: Spelling correction

2026-05-24T10:18:40Z

Spelling correction

Cholmondely: Moved screenshots to improve spacing of Dataset, minor formatting

2026-05-21T10:21:08Z

Moved screenshots to improve spacing of Dataset, minor formatting

Cholmondely: Tagged as an "OXP API", added screen shots

2026-05-21T08:52:23Z

Tagged as an "OXP API", added screen shots

Phkb: /* EInt Section */

2026-05-21T05:51:22Z

‎EInt Section

Phkb: /* EInt Section */

2026-05-21T05:49:22Z

‎EInt Section

Phkb: Created page with "This guide is designed to help you add Library Config into your OXP. Lib Config is a powerful tool that can make it super easy for player to customise your OXP in the ways yo..."

2026-05-21T05:44:24Z

Created page with "This guide is designed to help you add Library Config into your OXP. Lib Config is a powerful tool that can make it super easy for player to customise your OXP in the ways yo..."

New page

This guide is designed to help you add Library Config into your OXP.

Lib Config is a powerful tool that can make it super easy for player to customise your OXP in the ways you want them too. If they open your OXP and fiddle with things you *don't* want them to, all bets are off!

There are 3 possible parts to Library Config integration.<br>
1. Dataset<br>
2. Interface code<br>
3. Notify code

==1. Dataset==
The dataset required for Library Config is a dictionary with several distinct parts. Let's look at an example:

this._myConfig = {
Name: this.name,
Display: "Debug Options",
Alias: "My Super OXP",
Alive: "_myConfig",
Notify: "$generalChanges",
Reset: false,
Bool: {
B0: { Name: "_debug", Def: false, Hide: false, Notify: "$debugFlagChanges", Desc: "Turn on debug messages" },
Info: "0: Turn on/off debug messages sent to the log file",
Notify: "$generalFlagChanges"
}
SInt: {
S0: { Name: "_myValue", Def: 0.3, Min: 0, Max: 1, Float: true, Hide: false, Notify: "$myValueChanges", Desc: "My decimal value" },
Info: "0: Special decimal value used for important calculations",
Notify: "$generalValueChanges"
}
EInt: {
E0: { Name: "_myBitmask", Def: 0, Min: 0, Max: 15, OneOf: false, OneOfZero: true, Hide: false, Notify: "$myBitmaskChanges", Desc: ["Value 1", "Value 2", "Value 3", "Value 4"] },
Info: "0: Controls special settings",
Notify: "$generalBitmaskChanges"
}
};

The first line <code>this._myConfig</code> is the name we are giving to the dataset. It can be pretty much any combination of letters and numbers. Something meaningful is usually preferred.

This is followed by an <code>=</code> sign, and then an opening curly brace <code>{</code>, which signals what follows should be considered a dictionary, that is, key/value pairs, separated by commas. There is a closing curly brace at the end with a semi-colon <code>};</code> to mark the end of the dictionary.

Please note: key names are case sensitive. <code>name</code> doesn't equal <code>Name</code>. All the key values in a Lib Config dataset are Capitalised, so if you're getting errors when creating your dataset, check the key names for the correct format.

The first key/value pair is for <code>Name</code>. This is the worldScript name of where our dataset is being held. We could enter it as text, but the more reliable and easier to maintain method is to use <code>this.name</code> as the value.

Next is <code>Display</code>. This is the text that will be displayed in the "Settings" column in the Config display. This can be any text, but long values will be truncated.

Next is <code>Alias</code>. This is an optional value, and if not supplied the script name (ie what was entered into the <code>Name</code> key above) will be used. <code>Alias</code> allows us to put something more human-readable on the screen. This can be any text, but again, long values will be truncated.

Next is <code>Alive</code>. This is the name of your dataset, the same name we entered on the first line. The only difference is that you don't put <code>this</code> in front of it. It's just the name of your dataset on its own.

Next is <code>Notify</code>. This is the name of a function in your worldScript file that will be called whenever the user finishes making changes to your settings through Lib Config. This item is optional and is only used in specific circumstances. If you need to make other changes to various aspects of your OXP (for instance, changing the colour of something the player will see immediately), you would add a function and put the name of it here in <code>Notify</code>. Then in your function you could check the values that might have changed and perform any addition tasks those changes require.

Next is <code>Reset</code>. This is an optional boolean value. It will add a "Reset to default" menu option to your settings page, and is the reason why all the settings about to be described have a <code>Def</code> key. If the user selects the "Reset to default" option, Lib Config will set all your values back to their <code>Def</code> value.

We now get to the <code>Bool</code>, <code>SInt</code> and <code>EInt</code> sections. This is where we tell Lib Config what data we want it to interact with, and how to do that interaction. Each of these is another dictionary object (ie key/value pairs).

We'll start with the easy one first: <code>Bool</code>.

===<code>Bool</code> Section===
The <code>Bool</code> section deals with boolean values. ie. values that are either true or false. When you open your settings in Lib Config, this is the "Show Switches" menu item. The structure of the <code>Bool</code> dictionary is:

<code>Bn</code>: where "n" is a number between 0 and 8. For example <code>B0</code>, <code>B1</code> etc. Each of these are another dictionary, and they each define one boolean value.

<code>Info</code>: A text entry that adds some descriptive text to your boolean values screen. Generally this has been used to provide additional help and instructions that might be otherwise difficult to enter on an individual line.

<code>Notify</code>: The name of a function to call when the user leaves the "Show Switches" screen.

Each of the <code>Bn</code> dictionaries has the following key/value pairs:

<code>Name</code>: This is the name of your variable, and an accurate path to get to it. In it's most simple form, this can be something like <code>_debug</code>. What this means is there needs to be a definition in your script file of <code>this._debug = false;</code>, usually above the point where you're defining your Lib Config data (not that it will matter, but it makes it easier to read as a human).

Where is can get complicated is if you have a dictionary object with all your custom values in it. For example:

this._myData = {
debug: false,
myValue: 0.3,
myBitmask: 0
};

In this example, the "path" to the debug flag is <code>this._myData.debug</code>. When it comes to the enter in your config, you would leave off the <code>this.</code> and just enter <code>_myData.debug</code>.

Next we have <code>Def</code>. This is short for "default", and indicates what the default value for our flag is. For a boolean value, it can be either true or false.

Next is <code>Hide</code>. This is an optional key. This allows the value to be defined but not displayed to the user. This will only be used in very edge cases, so edge I'm not sure I can think of one!

Next is <code>Notify</code>. This is an optional key, and is the same as the overall settings <code>Notify</code>, in that it is the name of a function in your worldScript. The difference is that this function will be called every time the user changes the value.

Finally, we have <code>Desc</code>. This is the text that will appear beside the value, explaining what it does. You can put whatever text you like here, but the space is short and long entries will be truncated.

===<code>SInt</code> Section===
The <code>SInt</code> section deals with numerical data, both integers (or whole numbers) and decimal values. When you open your settings in Lib Config, this is the "Show Values" menu item. The structure is basically the same as the <code>Bool</code> section:

<code>Sn</code>: where "n" is a number between 0 and 8. For example, <code>S0</code>, <code>S1</code> etc. Each of these is another dictionary, and they each define one numeric value.

<code>Info</code>: A text entry that adds some descriptive text to your values screen.

<code>Notify</code>: The name of a function to call when the user leaves the "Show Values" screen.

Each of the <code>Sn</code> dictionaries has the following key/value pairs:

<code>Name</code>: As with the boolean entries, this is the name of your variable, and all the same rules apply.

Next we have <code>Def</code>, which is the default value for this variable. This can be whatever you need it to be, but it makes sense for it to have the same value as whatever you use in your definition. For example, if you have <code>this._myValue = 15.5;</code> in your script file, it makes sense to have <code>Def: 15.5</code> in your Lib Config entry for that variable.

Next we have <code>Min</code>. This is the minimum value your variable can have. Attempting to enter a value below this will fail and no value will be changed.

After this is <code>Max</code>. This is the maximum value your variable can have. Attempting to enter a value above this will fail and no value will be changed.

Next is <code>Float</code>. This is a boolean value indicating whether the variable is a decimal (ie with decimal points). This is an optional setting, and if omitted the default is "false", which means Lib Config will treat the value as an integer, and any decimals entered by the user will be stripped.

The last 3 entries are the same as for the <code>Bool</code> section. <code>Hide</code> will hide the entry on the display, <code>Notify</code> is a function that will be called whenever the user changes the value, and <code>Desc</code> is the short text description for the value, with long entries being truncated.

===<code>EInt</code> Section===
The <code>EInt</code> section is the least used section of Lib Config, largely because bitmasks are confusing. What are bitmasks, you ask? Well, in Oolite we do deal with bitmasks a little bit. Let me show you a small snippet from a random shipyard.plist file:

weapon_facings = 3;

The <code>weapon_facings</code> value is a bitmask. The possible values start at 1 and go up by a factor of 2 for each additional value. In the example from shipyard.plist, the possible values are 1 = Forward weapon, 2 = Aft weapon, 4 = Port weapon, and 8 = Starboard. So a value of 3 would mean 1 (forward) + 2 (rear), meaning only front and rear laser mounts.

Think of it like this: Imagine a panel of switches like this:
[XXXXXXXXXX]
Where "X" is a switch. Each of those switches can be turned on an off, like this:
[X..XXX..X.]
Where "X" is on and "." is off. Now, we could set up ten different flag varibles, which would work, but gets cumbersome when there are a lot of flags to track. So instead we can use a bitmask:
125
136251
1248624862
[XXXXXXXXXX]
The numbers here are read vertically (1, 2, 4, 8, 16, 32, 64, 128, 256, 512).

Converting the switch settings above into a single value would be (1 + 8 + 16 + 32 + 256) = 313

Given the fiddly nature of bitmasks, they are only likely to be used in certain conditions, but they can be a handy way to combine a lot of boolean values into one.

When it comes to the <code>EInt</code> section, there is only 1 entry: <code>E0</code>. The other sections can have 9, but in this section there is only one.

<code>Info</code>: This is the same as for the other sections, a text entry that adds some descriptive text to the data entry screen.

<code>Notify</code>: The name of a function to call when the user leaves the "Show Flags" screen.

The <code>E0</code> dictionary has the following key/value pairs:

<code>Name</code>: Same as the other section. This is the name of your variable, and all the same rules apply.

Next we have <code>Def</code>, which is the default value for this variable.

Next we have <code>Min</code>. This is the minimum value your variable can have. With a bitmask, this will either mean 0 or 1. If the value can have no flags set, the minimum value is 0. If there must be at least one flag set, the minimum value will be 1.

After this is <code>Max</code>. This is the maximum value your variable can have. With a bitmask, this will be either the sum of all the bits, or the value of the last bit. Which one it is will depend on how you are using your bitmask. If you're keeping track of multiple flags, then you are likely using a bitmask where multiple bits are set. If you're tracking something that can have only one state at a time, but there are a number of states it could be, then only one bit is being set. The max value can only be determined by understand how you are using your bitmask value.

The next two keys would never be in the settings at the same time.

<code>OneOf</code> means only one bit can be set at a time, but one *must* be set. You cannot have a zero value. If you can only have one bit set at a time, but "no bits" is a valid possibility, then you would use <code>OneOfZero</code>. Both of these can be excluded if you can have any number of bits set.

The next 2 entries are the same as for the <code>Bool</code> and <code>SInt</code> sections. <code>Hide</code> will hide the entry on the display, and <code>Notify</code> is a function that will be called whenever the user changes the value.

<code>Desc</code> is slightly different to the other sections. Rather than being one piece of text, this is an array of text items. The array should be the same size as the number of bits in your bitmask. So, if you have 10 bits, there should be 10 entries in the array. The text entries will be shown beside the bit values on the screen.

So, that's our Lib Config dataset established. Next, let's have a look at the interface code.

==2. Interface code==
The hard stuff has largely been done now. To add our settings into Lib Config, we put the following code into the <code>startUpComplete</code> function of our worldScript.

this.startUpComplete = function () {
// register our settings, if Lib_Config is present
if (worldScripts.Lib_Config) {
worldScripts.Lib_Config._registerSet(this._myConfig);
}
}

If you don't need to be notified when changes are made, that's it! However, there is one more worldScript function we should add.

this.playerWillSaveGame = function () {
if (worldScripts.Lib_Config) {
missionVariables.MyOXP_debug = this._debug;
missionVariables.MyOXP_myValue = this._myValue;
missionVariables.MyOXP_myBitmask = this._myBitmask;
}
}

If the player makes changes that need to be saved with the game, this is the spot to put it. Here, we are only saving the values if Lib Config is installed. If Lib Config is not present, the only way to change the values would be by editing the worldScript itself. If someone does that, they probably wouldn't want the values saved - they're making a global change, which probably shouldn't be overwritten by saved data.

If we're saving the data, we should also load it, so:

this.startUp = function () {
if (worldScripts.LibConfig) {
if (missionVariables.MyOXP_debug) this._debug = missionVariables.MyOXP_debug;
if (missionVariables.MyOXP_myValue this._myValue = parseFloat(missionVariables.MyOXP_myValue);
if (missionVariables.MyOXP_myBitmask = this._myBitmask = parseInt(missionVariables.MyOXP_myBitmask);
}
}

==3. Notify code==
Adding the notify functions would only be required if you defined one in your dataset. What goes into them will be unique to your OXP. But for example:

this.$debugFlagChanges = function() {
log(this.name, "Debug flag is now set to " + this._debug);
}

And that's it! Hopefully this guide has helped you unlock some of the potential in Library Config, and made the process of exposing internal settings a little bit easier.

← Older revision		Revision as of 08:52, 21 May 2026
Line 1:		Line 1:
		+	[[Image:IconLib.png\|100px\|right]]
		+	[[Image:Library (Config for AddOns Settings List).png\|320px\|thumb\|Config for AddOns (List of OXPs with settings)]]
		+	[[Image:Library (BGS Config Flags).png\|320px\|thumb\|Config for AddOns (example: BGS flags settings)<br>'''Flags''' are On/Off options, Values give a numerical range. (Old Hyperspace is added by Tsoj's newest version of BGS)]]
		+	[[Image:Library (BGS Config Values).png\|320px\|thumb\|Config for AddOns (example: BGS values settings)<br>'''Values''' ('''D''' is the default setting, '''R''' shows the range)]]
	This guide is designed to help you add Library Config into your OXP.		This guide is designed to help you add Library Config into your OXP.

Line 199:		Line 203:

	And that's it! Hopefully this guide has helped you unlock some of the potential in Library Config, and made the process of exposing internal settings a little bit easier.		And that's it! Hopefully this guide has helped you unlock some of the potential in Library Config, and made the process of exposing internal settings a little bit easier.
		+
		+	[[Category:OXP API's]]

@@ Line 20: / Line 20: @@
      Notify: "$generalChanges",
      Reset: false,
      Bool: {
        B0: { Name: "_debug", Def: false, Hide: false, Notify: "$debugFlagChanges", Desc: "Turn on debug messages" },
        Info: "0: Turn on/off debug messages sent to the log file",
        Notify: "$generalFlagChanges"
+    },
      SInt: {
        S0: { Name: "_myValue", Def: 0.3, Min: 0, Max: 1, Float: true, Hide: false, Notify: "$myValueChanges", Desc: "My decimal value" },
        Info: "0: Special decimal value used for important calculations",
        Notify: "$generalValueChanges"
+    },
      EInt: {
        E0: { Name: "_myBitmask", Def: 0, Min: 0, Max: 15, OneOf: false, OneOfZero: true, Hide: false, Notify: "$myBitmaskChanges", Desc: ["Value 1", "Value 2", "Value 3", "Value 4"] },
        Info: "0: Controls special settings",
        Notify: "$generalBitmaskChanges"
-−
+    }
    };
 [[Image:Library (BGS Config Flags).png|320px|thumb|Config for AddOns (example: BGS flags settings)<br>'''Flags''' are On/Off options, Values give a numerical range. (Old Hyperspace is added by Tsoj's newest version of BGS)]]

@@ Line 3: / Line 3: @@
 This guide is designed to help you add Library Config into your OXP.
-Lib Config is a powerful tool that can make it super easy for player to customise your OXP in the ways you want them too. If they open your OXP and fiddle with things you *don't* want them to, all bets are off!
+Lib Config is a powerful tool that can make it super easy for players to customise your OXP in the ways you want them too. If they open your OXP and fiddle with things you *don't* want them to, all bets are off!
 There are 3 possible parts to Library Config integration.<br>

@@ Line 147: / Line 147: @@
 Next we have <code>Min</code>. This is the minimum value your variable can have. With a bitmask, this will either mean 0 or 1. If the value can have no flags set, the minimum value is 0. If there must be at least one flag set, the minimum value will be 1.
-After this is <code>Max</code>. This is the maximum value your variable can have. With a bitmask, this will be either the sum of all the bits, or the value of the last bit. Which one it is will depend on how you are using your bitmask. If you're keeping track of multiple flags, then you are likely using a bitmask where multiple bits are set. If you're tracking something that can have only one state at a time, but there are a number of states it could be, then only one bit is being set. The max value can only be determined by understand how you are using your bitmask value.
+After this is <code>Max</code>. This is the maximum value your variable can have. With a bitmask, this will be either the sum of all the bits, or the value of the last bit. Which one it is will depend on how you are using your bitmask. If you're keeping track of multiple flags, then you are likely using a bitmask where multiple bits are set. If you're tracking something that can have only one state at a time, but there are a number of states it could be, then only one bit is being set. The maximum value can only be determined by understanding how you are using your bitmask value.
 The next two keys would never be in the settings at the same time.

@@ Line 116: / Line 116: @@
    weapon_facings = 3;
-The <code>weapon_facings</code> value is a bitmask. The possible values start at 1 and go up by a factor of 2 for each additional value. In the example from shipyard.plist, the possible values are 1 = Forward weapon, 2 = Aft weapon, 4 = Port weapon, and 8 = Starboard. So a value of 3 would mean 1 (forward) + 2 (rear), meaning only front and rear laser mounts.
+The <code>weapon_facings</code> value is a bitmask. The possible values (other than zero) start at 1 and go up by a factor of 2 for each additional value. In the example from shipyard.plist, the possible values are 1 = Forward weapon, 2 = Aft weapon, 4 = Port weapon, and 8 = Starboard. So a value of 3 would mean 1 (forward) + 2 (rear), meaning only front and rear laser mounts.
 Think of it like this: Imagine a panel of switches like this: