Galactic Hyperspace Behavior Upgrade for v1.71

[another_commander]

Those of you who thought that it has not been a great idea to exclude isolated systems or clusters of systems from galactic hyperspace destinations in Oolite will be happy to know that as of the upcoming release, Oolite will feature user control of galactic hyperspace behavior.

To facilitate this, we are using the planetinfo.plist. The key galactic_hyperspace_behaviour (note the British spelling) controls where the player will arrive after a G.H. has been executed. There are three possible types of G.H. behavior and are as follows:
1) Oolite standard. This is what we have up to this moment. Executing a G.H. jump will poisition the player in the next galaxy, to the closest non-isolated system with regards to their current galaxy coordinates. So, for example, if you jump from coordinates (100, 50) in galaxy 1 you will arrive in galaxy 2 at the same coordinates, unless these coordinates refer to an unreachable system, in which case the arrival point will be adjusted by the engine to maybe something like (102, 51). This is set as default behavior. It is set by assigning the string BEHAVIOUR_STANDARD to the galactic_hyperspace_behaviour key.
2) All systems reachable. Same as above, only this time we do not check for arrival at an isolated system. Using this method, systems like Oresrati in G8, the lower left hand cluster of systems in G7, the two islands of isolated systems in G6 etc. are now possible arrival points. If you land there, you may not be able to exit again, depending on the tech levels of the systems you get to. Mission scripters may want to use this. This behaviour is set by assigning the string BEHAVIOUR_ALL_SYSTEMS_REACHABLE to galactic_hyperspace_behaviour key in planetinfo.plist.
3) Fixed coordinates arrival point. This will make Oolite simulate some older 8-bit versions, that were putting the player in the same fixed point every time a galactic jump was performed, but there is also good potential for scripting (see below). This is set by assigning the string BEHAVIOUR_FIXED_COORDINATES to the galactic_hyperspace_behaviour key. If this method is chosen, then the engine will look in planetinfo.plist for a key named galactic_hyperspace_fixed_coords, from which it will read the actual coordinates that will be used as arrival point in the next galaxy. If none is found, then coordinates (96,96) will be used.

There is also the capability of using JavaScript methods to change both the galactic hyperspace behavior and the fixed coordinates, if one wants to use this. Currently we have player.ship.galacticHyperspaceBehaviour = ("[one of the above capitalized strings]") and player.ship.galacticHyperspaceFixedCoords = ([CoordX, CoordY, 0]). These are set as read/write. So, if you wanted to be able to G.H from Rainza in G7 and arrive at Oresrati in G8, now it can be done by scripting. The actual method names and other technical specifications are still under discussion and may change slightly in the future, but this is the general idea behind this all.

Edit: Spelling.
Edit2: Update methods names to current status.
Edit3: Update to 1.72.2 status.

[TGHC]

I am delighted that this has been addressed, when you say user control though, how will that actually work in gameplay.

I prefer option 2, so that remote systems are reachable. I've always savoured the idea of an OXP that awards a GH on arrival to Oresrati from Rainza in Galaxy 7, along the lines of a mission to find Raaxla!

[Rxke]

Yay! Good job.

[another_commander]

I am delighted that this has been addressed, when you say user control though, how will that actually work in gameplay.

I prefer option 2, so that remote systems are reachable. I've always savoured the idea of an OXP that awards a GH on arrival to Oresrati from Rainza in Galaxy 7, along the lines of a mission to find Raaxla!

User control means that the users can decide which method they prefer and edit the planetinfo.plist accordingly. Or rather - since editing core game files is discouraged - edit a copy of planetinfo.plist placed in a folder like AddOns/MyGH.oxp/Config. More importantly, it means that scripts can set how galactic hyperspace will work at the will of the scripter.

If you prefer option 2, you can set it up by simply editing planetinfo.plist and adding the line

Code: Select all

"galactic_hyperspace_behaviour" = "BEHAVIOUR_ALL_SYSTEMS_REACHABLE";

or having a script that will do something like

Code: Select all

player.ship.galacticHyperspaceBehaviour = "BEHAVIOUR_ALL_SYSTEMS_REACHABLE";

when the script conditions are met. If you want Rainza-leads-to-Oresrati into the mix, you could write your script so that it does this in the shipWillEnterWitchspace handler:

Code: Select all

this.shipWillEnterWitchspace = function(cause)
{
	if (system.name == "Rainza") 
	{
		if (cause == "galactic jump") // GH from Rainza will lead to Oresrati, as the legend dictates.
		{
			log ("jstest.witchSpace.begin", "Executing intergalactic jump from Rainza, G7. Setting jump destination to Oresrati, G8.");
			player.ship.galacticHyperspaceBehaviour = "BEHAVIOUR_FIXED_COORDINATES";
			player.ship.galacticHyperspaceFixedCoords = ([16, 255, 0]); // Oresrati, G8.
		}
	}
}

Next time a GH is executed, the arrival point will be Oresrati, as long as the departure system is Rainza.

As you understand, scripts can modify this behaviour on the fly. Meaning that, in the same game you can start with the default behaviour and, when the script decides, switch to fixed coordinates, execute a GH to the fixed coordinates and then switch GH mode to all systems reachable, if this is what the scripter wanted to do. The three options you have are interchangable, although obviously only one of them can be active at any time. The system is designed so that upon loading up of a new player all GH variables are restored to their default values. Default will be whatever the user has set in their planetinfo.plist. If there are no GH settings in planetinfo.plist, then the engine will use the standard behaviour that we have always had.

Edit: Changed wording to refer to a copy of planetinfo.plist. Editing core game files directly is generally discouraged.
Edit2: Replaced script pseudocode with actual, tested on development build code.
Edit3: Updated methods to current status.
Edit4: Update to 1.72.2 status.

[Commander McLane]

Thanks, has my vote!

@TGHC: "user controlled" here means actually "scripter controlled". But you may, of course, script yourself.

[another_commander]

"user controlled" here means actually "scripter controlled". But you may, of course, script yourself.

It may also include any user who decides that they don't want the standard behaviour and change the defaults in their planetinfo.plist, even if no scripts are running at all.

[davcefai]

Since we're on this subject, are there any plans to resurrect Galaxy 9 and "Archangel" status?

I think that in Elite for the PC they were somehow related but I forget how.

[another_commander]

Since we're on this subject, are there any plans to resurrect Galaxy 9 and "Archangel" status?

I think that in Elite for the PC they were somehow related but I forget how.

I have some secret plans about one of the two things you have mentioned, but I don't want to talk too much about it. They will require approval from Ahruman and the other devs and besides, they are top secret, you know...

[TGHC]

"user controlled" here means actually "scripter controlled". But you may, of course, script yourself.

It may also include any user who decides that they don't want the standard behaviour and change the defaults in their planetinfo.plist, even if no scripts are running at all.

For those of us who are dyslexic, or clueless about scripting this is not a good solution.

[davcefai]

I have some secret plans.......

I always get confused about this. Which of us will have to kill the other?

[JensAyton]

For those of us who are dyslexic, or clueless about scripting this is not a good solution.

The solution in that case is to ask for someone to write an OXP that does things the way you want. :-)

[Commander McLane]

One question: The JavaScript-example seems to suggest that you can set or reset galactic_hyperspace_behaviour also from a script, meaning you could make all systems reachable only for a certain point of your storyline.

Does that work with the legacy-methods setPlanetinfo: and/or setSpecificPlanetInfo:?

*****

Thinking a little more I think I may have discovered a problem with the planetinfo.plist-key. I assume it works globally, not locally only within one OXP? (I'm not sure about that, but I generally suspect this to be the case for planetinfo.plist.)

So, my question: What happens if one scripter in the planetinfo.plist of his OXP sets

Code: Select all

"galactic_hyperspace_behaviour" = "GALACTIC_HYPERSPACE_BEHAVIOUR_ALL_SYSTEMS_REACHABLE";

another scripter in another OXP sets

Code: Select all

"galactic_hyperspace_behaviour" = "GALACTIC_HYPERSPACE_BEHAVIOUR_STANDARD";

and a third scripter in his completely unrelated OXP sets

Code: Select all

"galactic_hyperspace_behaviour" = "GALACTIC_HYPERSPACE_BEHAVIOUR_FIXED_COORDINATES";

???

The usual handling would be that one value overwrites the previous, so in the end galactic_hyperspace_behaviour would have the value specified by the OXP whose name is last in alphabetical order.

Haven't we introduced a perfect way, in which one OXP unwillingly and unknowingly can break another one? At the end of the day OXP A and B are relying on a galactic_hyperspace_behaviour that has already be changed by OXP C.

The only way out of this in my opinion would be to make galactic_hyperspace_behaviour work only locally in the context of the OXP that has defined it, analogous to a local_variable. But (1) I don't think that's even possible for planetinfo.plist-keys, and (2) the player could still play through two missions with different galactic_hyperspace_behaviour-settings at the same time. So which one should govern the next jump?

The longer I think the more I'm afraid we have layed something like a cuckoo's egg in our Oolite nest.

[another_commander]

This is a potential problem, that is true. Scripts changing arbitrarily the galactic jump behaviour can affect eachother's results.

The scripters should take care of this. After resetting the galactic hyperspace behaviour to what they need for their script, they should also cater for it to be changed back after the GH change has served its purpose. This was the main reason for implementing the querying JS methods player.galacticHyperspaceBehaviour and player.galacticHyperspaceFixedCoords. As a first step, we get the current status of GH behaviour, we store it, then set it to whatever we need, do our jump to destination and finally reset everything back to previous state.

It is best if the change in galactic hyperspace status happens only at the very last moment before the jump.

[Commander McLane]

Therefore my first question again: Can I do it in legacy scripting as well, with either setPlanetinfo: or setSpecificPlanetInfo:?

If yes, then I would reset it to its default after jumping, because the thing I can't do in legacy scripting is querying it, right?

And because of its potential to break other peoples OXPs, it should be made very clear in the documentation (wiki or wherever), that it must be set shortly before a jump only, and reset afterwards.