Download for just looking at it: OXPAdditionalCargoSpaceWorkaround_0.1.0.oxz
And something to play with: ACSA.oxz
(Beware! It might contain bugs, so don't overwrite old savegames!)
This tread is about the "OXP Additional Cargo Space Workaround" (project name, that might change) and ways to improve it or how to reach a certain development goal and manage to still completely avoid this workaround, which is preferable, as it has unavoidable shortcomings/design flaws (and how to overcome this flaws
).!!! This here presented workaround is still in its development phase and certain features might change! If you want to use it for your OXP, make sure to come back and check for a gold release. This gold release should have implemented an final missionVariable string format and a list of methods, that won't change afterwards anymore, to provide a long lasting compatibility for your OXP and future ones. !!!
I have to ask the moderators, if they'll be so kind to move this tread to the Expansion section, when it is time.
Why is there a need for such a workaround? (Is there a need at all?):
There are methods implemented, that allow OXPs to modify the size so the cargo hold of a ship. This is a good thing, of course. But the problem lies in the fact, that this storage room modifications aren't permanent. Additional cargo space gained this way might be used for commodities or equipment, but after the game has been saved and is then restored from this savegame, this room is gone and commodities and equipment, that depended on its existence, aren't restored from that savegame either. In the case of equipment items, this might happen to passenger berths too, which means, that passengers might also be lost.
An OXP developer might now try to create his/her own workaround for his/her OXP, but a general workaround means a lot of messing around with the game data values and in the end that workaround will still only work with the own OXP. It would prove to be very incompatible with other OXPs, especially those, which try to archive similar goals.
This workaround here presents this already completed approach, which provides script methods to increase the cargo hold and handles, what comes afterwards. All OXPs that use this workaround should at least be compatible with each other at least in this hind side. Sadly not all conflict points with other OXPs could have been removed (read below for reasons), but many approaches have been implemented to keep conflicts at a minimum.
To the question, if it is needed. Well, the cargo hold size is one of the most important values in oolite game play wise. Being able to modify it, bring new possibilities for OXPs. But this workaround isn't about new OXPs, that can be thought of. It is meant for those OXPs, that were thought of first and can't be realized without it, if you get what I mean. Currently the source code doesn't allow a clean method to allow this. Until the day arrives, when it does, this here stands as one of the very few options one has.
How does it work?:
This workaround is implemented as a script. How the additional cargo space comes part of your ship is managed by your OXP. Before a new savegame is written, this script checks which values are in danger to be dropped and saves them if necessary as a missionVariable. When that savegame is loaded again, at first those values might actually not be restored by the game. Only while in the startUp-phase, when this script's or any other script's, using this workaround, startUp-method is called, the restoration process begins. First the script calls the new "OXPACSWaddPhase()" method in your OXP to ask your OXP, how much space it has added to the ship before saving and adds it asap. After that the rest of the stored data is restored and nearly every value should be like before saving the game.
How do I use it in my OXP?:
One step is to make sure the workarounds script is also loaded into oolite, when your OXP is installed. There are two methods to do this:
-The first method is to install this workaround in its OXP (OXZ) version and to create your OXP seperatly, but with a dependence on the workarounds OXP. You can find some help on how to do this here: Manifest.plist#Dependency management keys
You need to add the following lines to "manifest.plist" in your OXP's root directory.
Code: Select all
"requires_oxps" = (
{
"identifier" = "oolite.oxp.ocz.OXPAdditionalCargoSpaceWorkaround";
"description" = "OXPAdditionalCargoSpaceWorkaround";
}
);Afterwards you have to interconnect your OXPs scripts with the workaround's one. Read the section below, on how to do this.
-The second method is to take the latest version of the script and put in directly into your OXP. This might create problems with OXPs, that are using newer versions of this workaround in the future, as those might contain critical bugfixes or compatibility improvements for newer versions of oolite. But it allows your OXP to stand alone without dependences.
To do that, you place it in the "Scripts" folder of your OXP and create an entry for it in "world-scripts.plist" in the "Config" folder. Create "world-scripts.plist" if necessary.
Code: Select all
(
OXPAdditionalCargoSpaceWorkaroundScripts.js
(other scripts)
)
Modify your script file in the following manner:
Code: Select all
/*Head of you script*/
this.licence = "CC BY-NC-SA 4.0";
// Copy these lines into your script.
/* This will create an array, if in doesn't already exist, and pushes your scripts name into it. Its purpose is to include all scripts by every OXP using the OXP Additional Cargo Space Workaround Script.*/
if (!OXPACSWCrossScriptList) var OXPACSWCrossScriptList = [];
OXPACSWCrossScriptList.push(this.name);
this._runOXPACSWStartUp = function () {
if (worldScripts["OXPAdditionalCargoSpaceWorkaround Script"].startUp) {
worldScripts["OXPAdditionalCargoSpaceWorkaround Script"].startUp();
if (worldScripts["OXPAdditionalCargoSpaceWorkaround Script"].startUp)
delete worldScripts["OXPAdditionalCargoSpaceWorkaround Script"].startUp;
}
}
//This method will be used to add cargo space, when a gamestate is restored.
this._addCargoSpace = function (inputValue) {
if (worldScripts["OXPAdditionalCargoSpaceWorkaround Script"].OXPACSWAddCargoSpace)
worldScripts["OXPAdditionalCargoSpaceWorkaround Script"].OXPACSWAddCargoSpace(inputValue);
}
/* This method will be called by the workaround script to determine how much space is added by your OXP when a gamestate is restored.*/
this.OXPACSWaddPhase = function () {
delete this.OXPACSWaddPhase;
// Add your code here
// This is an example.
if (player.ship.equipmentStatus("EQ_EXAMPLE") === "EQUIPMENT_OK") this._addCargoSpace(3); // If "EQ_EXAMPLE" is onboard your ship, the cargo hold is 3t bigger.
}
this.startUp = function () {
// And add this line at the beginning of your scripts startUp-method
this._runOXPACSWStartUp();
// Rest of the startUp-method.
}
To be aware of/flaws in the workaround:
There are several quite worrying problems in this workaround. Some might be overcome by simple bugfixes, some by future changes in the oolite source, but some are the result of a fundamental design flaw of this approach.
Known issues:
- This code corrects important data values after the game has set them up, by modifying them. This happens in the startUp-phase, as this is the earliest point, when this is possible. But this might be too late, as there is no guaranty, that other OXPs startUp() methods aren't run before the workaround's! When this happens, it is thinkable, they might make modifications based on the unmodified data values, that are later undone by the workaround, when it is its turn. Or they check for commodities, equipments or passengers, that haven't been restored at this point. This would obviously create mistakes and inconsistencies. There have several steps been taken to counter this.
The workarounds script's name begins with a series of "a"s [has to be implemented] to put it wide ahead in the alphabetic order, that is used by oolite. (There still is no guaranty, it runs as first world script.)(Won't work: Scripters cove on this.)- The names of scripts of OXPs using the workaround are collected beforehand, to execute their OXPACSWaddPhase() methods directly in one go.
- The workarounds startUp() method is called directly in case an OXP's world script runs before it.
-When several workaround scripts are loaded, what might happen if several OXPs bring their own versions, there is no way to ensure the script with the highest version number is being used. An outdated version of this workaround, contained in an aged OXP, might "overwrite" newer versions. In worst case, this outdated version might be incompatible with a future version of oolite. The only way to solve that conflict, is to delete that outdated script file from the OXP's directory or the OXZ's archive file.
[to be continued.]
