Lib GUI

Overview

Lib_GUI (part of Library) is an attempt to manage multiple background-image AddOns, as far as JavaScript can do the job. It works in a relative simple way - AddOns can just write their Sets to the Objects $guis, $IDs and AddOns with missionscreens can declare rules in $IDRules. As only one Set is in use, players won't get style mixtures anymore (for full Sets). The inserted full Sets are user-selectable at runtime through Lib_Config.

But JavaScript can handle it only when it is executed. If the application starts or the game is paused, you'll still need to declare a few images in screenbackgrounds.plist.

Preparation

manifest.plist

Add to your manifest.plist

 requires_oxps = (
   {
     identifier = "oolite.oxp.Svengali.Library";
     version = "1.0";
     description = "Depends on Library 1.0.";
   }
 );

screenbackgrounds.plist

Use these keys in screenbackgrounds.plist

 {
   intro              = guiTextureSpecifier;
   keyboardsettings   = guiTextureSpecifier;
   load_save          = guiTextureSpecifier;
   newgame            = guiTextureSpecifier;
   oxz-manager        = guiTextureSpecifier;
   settings           = guiTextureSpecifier;
   shiplibrary        = guiTextureSpecifier;
   long_range_chart_mission = "lib_black.png"; // any full black texture
   short_range_chart_mission = "lib_black.png";
 }

Full Sets

Registering a GUI-Set

	worldScripts.Lib_GUI.$guis[this.name] = object;

Register a data set for standard GUIs (all screens without screenID) on .startUp.

Possible entries:

GUI_SCREEN_EQUIP_SHIP, GUI_SCREEN_GAMEOPTIONS, GUI_SCREEN_INTERFACES, GUI_SCREEN_KEYBOARD, GUI_SCREEN_LOAD, GUI_SCREEN_LONG_RANGE_CHART, GUI_SCREEN_MANIFEST, GUI_SCREEN_MARKET, GUI_SCREEN_MARKETINFO, GUI_SCREEN_OPTIONS, GUI_SCREEN_REPORT, GUI_SCREEN_SAVE, GUI_SCREEN_SAVE_OVERWRITE, GUI_SCREEN_SHIPLIBRARY, GUI_SCREEN_SHIPYARD, GUI_SCREEN_SHORT_RANGE_CHART, GUI_SCREEN_STATUS, GUI_SCREEN_STICKMAPPER, GUI_SCREEN_STICKPROFILE, GUI_SCREEN_SYSTEM_DATA

Example:

 worldScripts.Lib_GUI.$guis[this.name] = {
   generic: {pic:guiTextureSpecifier},
   GUI_SCREEN_EQUIP_SHIP: {pic:"xyz.png", ov:"xyz.png", snd:"xyz.ogg"},
   ...
 };

The Object members are:

pic

guiTextureSpecifier.

picFlight

guiTextureSpecifier. Inflight only.

picNova

guiTextureSpecifier. On GUI_SCREEN_SYSTEM_DATA only.

picRed

guiTextureSpecifier. Inflight only.

picVoid

guiTextureSpecifier. Docked only if station.script has $guiVoid set.

ov

guiTextureSpecifier.

snd

sound declaration.

sndRef

any other Set (e.g. "BGS").

All "pic" and "ov" members can use suffixes to handle additional stuff:

"Red"

For alertCondition === 3.

"Big"

For HUDs which are designed to allow big screens (hudAllowsBigGui).

So it's possible to use e.g. "pic", "picBig", "picRed" and "picRedBig".

If your are using Objects for guiTextureSpecifier, e.g. {name:"xyz.png"} you can use Norbys scaling by adding scale: {x:pixel,y:pixel,zoom:level}.

As you can see an additional member is used: "generic". This is used to catch all GUIs which are not declared.

Registering an ID-Set

	worldScripts.Lib_GUI.$IDs[this.name] = object;

Register a data set for screens with screenID on .startUp or later.

Example:

 worldScripts.Lib_GUI.$IDs[this.name] = {
   generic: {pic:"xyz.png", mpic:"xyz.png", ov:"xyz.png"},
   "oolite-contracts-cargo-none": {pic:"xyz.png", snd:"xyz.ogg"},
   "oolite-contracts-cargo-details": {mpic:"xyz.png", snd:"xyz.ogg"}, //!!!
   ...
   "my_oxp_custom_screen": {pic:"xyz.png", snd:"xyz.ogg"}
 };

The object members are (all optional):

mpic

guiTextureSpecifier. For screens which are using backgroundSpecial.

pic

guiTextureSpecifier.

ov

guiTextureSpecifier.

snd

sound declaration.

sndRef

any other Set (e.g. "BGS").

All "mpic", "pic" and "ov" members can use suffixes to handle additional stuff:

"Big"

For HUDs which are designed to allow big screens (hudAllowsBigGui).

So it's possible to use e.g. "pic", "picBig".

If your are using Objects for guiTextureSpecifier, e.g. {name:"xyz.png"} you can use Norbys scaling by adding scale: {x:pixel,y:pixel,zoom:level}.

As you can see one additional member is used: "generic". This is used if an OXP has registered a screenID rule, but is not defined in the current IDSet. It's optional.

Note: Another important thing is the details screens in Oolites cargo, parcel and passenger screens (mpic). If an OXP would set an background on these screens the map will disappear. This means that these screens need to be done via overlay! Sooo. The used image needs an alpha channel with the map area cut out (or alpha <0.5).

Extensions

Setting rules for custom IDs

	worldScripts.Lib_GUI.$IDRules["MY_OXP_SCREEN_ID"] = object;

Custom rules for your screenIDs can be set, but rules are shared, so do not change existing ones if they are not yours.

Example:

 worldScripts.Lib_GUI.$IDRules["MY_OXP_SCREEN_ID"] = {pic:1,snd:1,mus:1};

The object members are:

mpic

0 disallow, 1 allow - Set this to 1 if you are using backgroundSpecial.

pic

0 disallow, 1 allow - Image. Ignored if mpic is set.

ov

0 disallow, 1 allow - Image. Ignored if mpic is set.

snd

0 disallow, 1 allow - If a GUI sound is still playing.

mus

0 disallow, 1 allow - Continue music in Lib_Music.

Temporary GUI override

	worldScripts.Lib_GUI.$guisExt.GUI_SCREEN_REPORT.push(object);

AddOns which are meant as replacements for single GUI screens (e.g. HDBG) can write to $guisExt. If content is available the first entry will be used instead of the full Set until the Array is empty. After display the first entry gets removed. In the end a FIFO system (first-in, first out). See Registering a GUI-Set for the object members.

Global custom IDs

	worldScripts.Lib_GUI.$IDsExt["MY_OXP_SCREEN_ID"] = {pic:"xyz.png"};

Declarations for custom screenIDs can be written to $IDsExt. Like any other missionscreen it will need a rule defined. See Registering an ID-Set for the object members.