MasterClass: How to OXP (updating SoThisTC)

[andrax_iON]

Does this work?

Like a charm - thnx Spara & montana. I did get Diziet's version ok, guess I read 'minimal setup' as 'minimum requirements' so thought Spara's was necessary. Console's up & running after much d!cking around with python2/twisted/python-tk (python3 is throwing a syntax error on DebugConsole.py), first test shortly..

cheers!

Edit : tested, working; saved on Zaonce, admired the new station on the way in (v. nice!), TAF functioning, fuel + EQ goodies safely stowed. Phew!

[spara]

Does this work?

Like a charm - thnx Spara & montana. I did get Diziet's version ok, guess I read 'minimal setup' as 'minimum requirements' so thought Spara's was necessary. Console's up & running after much d!cking around with python2/twisted/python-tk (python3 is throwing a syntax error on DebugConsole.py), first test shortly..

cheers!

You're welcome. I'll be modifying my original version when we move on, so there might be some differences here and there. Should not be a problem though. And yes, the debug console could be a bit tricky to get working, but it's totally worth it if you get into tweaking business.

[spara]

Let's take a detailed look at the OXPs in question and plan a bit.

Sothis.oxp folder has the basic set of subfolders for this type of OXP: Config, Models, Scripts, Shaders and Textures. Models, Shaders and Textures include files for the actual model and since we're not tweaking the actual model, those can be ignored. That leaves us with Config and Scripts.

Config

• demoships.plist: Adds the station model to the Oolite opening screen. Not really of interest to us.
• script.js: This is the world script of this OXP. It stays in memory, stays active and defines if something special should happen on world script event triggers. This is of interest to us. http://wiki.alioth.net/index.php/Oolite ... t_handlers
  • The methods included are this.scrambledPseudoRandom and this.shipWillExitWitchspace. The first one is now obsolete, since Oolite has an inbuilt method for pseudorandom numbers. The second one defines the station to be spawned when exiting witchspace. This is a deprecated method and should be replaced with a proper populator. All in all this script is of no use to us.
• shipdata.plist: This includes properties for the station and the buoy. This is of interest to us. http://wiki.alioth.net/index.php/Shipdata.plist
  • This is a bit of mess to sort out, but it seems to work and we'll just replace some of the properties.

Scripts

• sothisscript.js: This is a ship script for the station. It defines if something special should happen on ship script event triggers. This could be of interest to us.
  • This one has just one method, this.shipSpawned, which triggers when the station is spawned and spawns the station buoy to the front of the dock. Works just fine.

Sothis_TC.oxp is an overriding OXP which modifies Sothis. Ethics on such action aside, let's see what's inside the OXP.

Config

• descriptions.plist: Includes the text strings for the docking welcome screen.
• shipdata-overrides.plist: Includes shipdata overrides for Sothis.oxp.
• world-scripts.plist: Sothis_TC has more than one world script so instead of using script.js we have to put the scripts to the Scripts folder and list them here.

Images: Background images for the welcome screen. One for each sector/galaxy.
Scripts

• sothis_tc.js: This is the main script which handles spawning, welcome screen and tradenet freebie.
• sothis_tc_new_cargoes.js. This registers Sothis as new cargoes station and defines the special goods market of Sothis stations.

We'll upgrade the oxp one feature at time. In the next post we'll fix spawning of the station to properly use populator. This will allow saving at the station if wanted. And if I understood it correctly will keep the Random Station name unchanged, if you're using the oxp.

[spara]

There are all sorts of spawn methods in Oolite. Most of them are for backward compatibility though. The preferred methods are addShips/addGroup and addShipsToRoute/addGroupToRoute. Since we are just adding one object to a fixed position and not dealing with groups we'll be using addShips.

Spawning is possible at any time, but stations especially are preferred to be spawned using a populator as part of the system population. If you think of the game as a theater, the population step is setting the stage ready.

With regards to the Sothis, which is an old OXP and for which we are using an overriding method, two things are needed:

1. suppress the original (and deprecated) spawning functionality.
2. reintroduce the spawning functionality by using populator.

1. Suppressing the original spawning functionality

Look at the script.js inside the original Sothis. The method this.shipWillExitWitchSpace handles spawning and need to be dealt with. The whole method can be deleted from the script of course, but if we want to keep the original intact for licensing issues or what ever, then we need to nullify the function in an overriding oxp.

Let's nullify. Look at the sothis_tc.js inside SothisTC. In this.startUp you see this:

Code: Select all

	if(!worldScripts["Spawn-sothis"]) { //check for sothis station oxp
		delete this.shipWillExitWitchspace;
		delete this.$addSothis;
		delete this.shipDockedWithStation;
		delete this.playerBoughtEquipment;
		delete this.shipLaunchedFromStation;
		player.consoleMessage("Sothis OXP is not installed, exiting SothisTC.", 5);
		log("SothisTC","Sothis OXP is not installed, exiting SothisTC.");
	}
	else {
		delete worldScripts["Spawn-sothis"].shipWillExitWitchspace;
		this.$addSothis();
	}

It checks for the presence of Sothis oxp by looking for it's world script and acts accordingly. If Sothis oxp is not present the functionality of SothisTC is effectively neutered. If Sothis oxp is present, then this.shipWillExitWitchSpace method is deleted from from memory to prevent it from spawning the station. This is done in startUp step which happens before anything else happens.

SothisTC also uses the same deprecated method for adding stations. The trigger for spawning is this.shipWillExitWitchspace and the actual spawning logic is in this.$addSothis. Lucky us, the spawning logic works just fine, so we can easily modify it to use populator. You can also find a call to this.$addSothis from startUp. That's there because one might save/reload at the main station and in that case shipWillExitWitchspace will not happen and the station would not be there. This is an old school thingy, so remove that call from the else clause.

2. Modify the the spawning functionality to use populator

Populators are executed when the system is to be populated. Before that happens, systemWillPopulate will trigger to set the populators.

Change this.shipWillExitWitchspace to this.systemWillPopulate to move the spawning functionality to a correct step. Do this change also to the neutering part to prevent script errors.

The only thing we need to change in this.$addSothis is replace "system.addShips("sothis", 1, [x, y, z]);" with a proper populator:

Code: Select all

		var exactPosition = [x, y, z];
		system.setPopulator("sothis_tc", {
			callback: function(pos) {			
				system.addShips("sothis", 1, pos, 0);					
			}.bind(this),
			location: "COORDINATES",
			coordinates: exactPosition,
			deterministic: true
		})

Shift-start the game, load your save game, lauch, and see if Sothis is there or not. It's also a good idea to look at the Latest.log if there's something funky there. If all goes well you should now be able to save at the station.

The positioning of the station is currently a bit complicated geometry-wise. To make changes to the positioning requires a bit understanding on the coordinate system used by oolite and some vector calculus. If you just want to push the station farther from the planet, adding a >1 multiplier to the c variable probably does the trick. If you want to do something more ambitious, then we need to have a short lesson on Oolite coordinate system and vectors.

[Cholmondely]

There are all sorts of spawn methods in Oolite. Most of them are for backward compatibility though. The preferred methods are addShips/addGroup and addShipsToRoute/addGroupToRoute. Since we are just adding one object to a fixed position and not dealing with groups we'll be using addShips.

Spawning is possible at any time, but stations especially are preferred to be spawned using a populator as part of the system population. If you think of the game as a theater, the population step is setting the stage ready.

With regards to the Sothis, which is an old OXP and for which we are using an overriding method, two things are needed:

1. suppress the original (and deprecated) spawning functionality.
2. reintroduce the spawning functionality by using populator.

1. Suppressing the original spawning functionality

Look at the script.js inside the original Sothis. The method this.shipWillExitWitchSpace handles spawning and need to be dealt with. The whole method can be deleted from the script of course, but if we want to keep the original intact for licensing issues or what ever, then we need to nullify the function in an overriding oxp.

Let's nullify. Look at the sothis_tc.js inside SothisTC. In this.startUp you see this:

Code: Select all

	if(!worldScripts["Spawn-sothis"]) { //check for sothis station oxp
		delete this.shipWillExitWitchspace;
		delete this.$addSothis;
		delete this.shipDockedWithStation;
		delete this.playerBoughtEquipment;
		delete this.shipLaunchedFromStation;
		player.consoleMessage("Sothis OXP is not installed, exiting SothisTC.", 5);
		log("SothisTC","Sothis OXP is not installed, exiting SothisTC.");
	}
	else {
		delete worldScripts["Spawn-sothis"].shipWillExitWitchspace;
		this.$addSothis();
	}

It checks for the presence of Sothis oxp by looking for it's world script and acts accordingly. If Sothis oxp is not present the functionality of SothisTC is effectively neutered. If Sothis oxp is present, then this.shipWillExitWitchSpace method is deleted from memory to prevent it from spawning the station. This is done in startUp step which happens before anything else happens.

SothisTC also uses the same deprecated method for adding stations. The trigger for spawning is this.shipWillExitWitchspace and the actual spawning logic is in this.$addSothis. Lucky us, the spawning logic works just fine, so we can easily modify it to use populator. You can also find a call to this.$addSothis from startUp. That's there because one might save/reload at the main station and in that case shipWillExitWitchspace will not happen and the station would not be there. This is an old school thingy, so remove that call from the else clause.

2. Modify the the spawning functionality to use populator

Populators are executed when the system is to be populated. Before that happens, systemWillPopulate will trigger to set the populators.

Change this.shipWillExitWitchspace to this.systemWillPopulate to move the spawning functionality to a correct step. Do this change also to the neutering part to prevent script errors.

The only thing we need to change in this.$addSothis is replace "system.addShips("sothis", 1, [x, y, z]);" with a proper populator:

Code: Select all

		var exactPosition = [x, y, z];
		system.setPopulator("sothis_tc", {
			callback: function(pos) {			
				system.addShips("sothis", 1, pos, 0);					
			}.bind(this),
			location: "COORDINATES",
			coordinates: exactPosition,
			deterministic: true
		})

Shift-start the game, load your save game, launch, and see if Sothis is there or not. It's also a good idea to look at the Latest.log if there's something funky there. If all goes well you should now be able to save at the station.

The positioning of the station is currently a bit complicated geometry-wise. To make changes to the positioning requires a bit understanding on the coordinate system used by oolite and some vector calculus. If you just want to push the station farther from the planet, adding a >1 multiplier to the c variable probably does the trick. If you want to do something more ambitious, then we need to have a short lesson on Oolite coordinate system and vectors.

Initial questions:
•spawn: is this just jargon for the creation of ships, asteroids/rick hermits etc & stations? Or is there more involved?
•populator: Is this just referring to the chunk of gamecode which spawns things?
•world script ? Help!
•adding a >1 multiplier to the c variable ? Help!

I did sneek a peek at OXP howto dockable stations which to my untutored eye looks unfinished. I skimmed Chapter 1.

Personally, I would rather cover more ground at less depth - eg look at various aspects of the Sothis.oxp at less depth, but gain an appreciation of context.

Then I can revisit other aspects later, and I will have the appropriate context to understand them and ask fewer stupid questions!

Thank you for taking the opportunity to explain and put things in context, even if I need a bit of help with the jargon!

[spara]

Initial questions:
•spawn: is this just jargon for the creation of ships, asteroids/rick hermits etc & stations? Or is there more involved?
•populator: Is this just referring to the chunk of gamecode which spawns things?
•world script ? Help!
•adding a >1 multiplier to the c variable ? Help!

I did sneek a peek at OXP howto dockable stations which to my untutored eye looks unfinished. I skimmed Chapter 1.

Personally, I would rather cover more ground at less depth - eg look at various aspects of the Sothis.oxp at less depth, but gain an appreciation of context.

Then I can revisit other aspects later, and I will have the appropriate context to understand them and ask fewer stupid questions!

Thank you for taking the opportunity to explain and put things in context, even if I need a bit of help with the jargon!

Good questions. Please ask questions when you don't understand something and I do my best to explain. I don't think we can avoid the "going deep" parts if you want to be able to do changes. But onwards, here be the answers to your questions.

1. Spawning is a somewhat common term for the creation of in-game objects. Nothing more.

2. Populators. Let's see. First of all, you need to understand the way Oolite works. The only system "alive" is the one the player is at. The other systems don't basically exist inside the game. When the player jumps to a system, the target system is set up and kicked to life. This happens in steps. One of the steps is the population step. In that step the system is populated with stations, ships, asteroids and so on. That happens by calling all populators that are set with system.setPopulator. The this.systemWillPopulate event has happened before the population step to allow different populators to be defined.

3. World script. This is one of the fundamental things that needs to be understood. World script is a script that's permanently in memory and is ready to respond to events triggered by the game. Oxps that basically do any sort of scripting have at least one world script defined. See http://wiki.alioth.net/index.php/Oolite ... t_handlers to find out what kind of events the script can respond to. For example systemWillPopulate is an event for which SothesTC now responds to.

4. In the code there is a line starting "var c=...". That is a variable definition. Adding a multiplier simply means changing that to "var c=2*..." or equivalent. That 2 is the multiplier and it needs to be greater than 1 to push the station further.

[Cholmondely]

I don't think we can avoid the "going deep" parts if you want to be able to do changes.

You, sir, are the professional, so I defer to your judgement.

[Cholmondely]

Look at the script.js inside the original Sothis. The method this.shipWillExitWitchSpace handles spawning and need to be dealt with. The whole method can be deleted from the script of course, but if we want to keep the original intact for licensing issues or what ever, then we need to nullify the function in an overriding oxp.

Let's nullify. Look at the sothis_tc.js inside SothisTC. In this.startUp you see this:

Code: Select all

	if(!worldScripts["Spawn-sothis"]) { //check for sothis station oxp
		delete this.shipWillExitWitchspace;
		delete this.$addSothis;
		delete this.shipDockedWithStation;
		delete this.playerBoughtEquipment;
		delete this.shipLaunchedFromStation;
		player.consoleMessage("Sothis OXP is not installed, exiting SothisTC.", 5);
		log("SothisTC","Sothis OXP is not installed, exiting SothisTC.");
	}
	else {
		delete worldScripts["Spawn-sothis"].shipWillExitWitchspace;
		this.$addSothis();
	}

2. Modify the the spawning functionality to use populator

Populators are executed when the system is to be populated. Before that happens, systemWillPopulate will trigger to set the populators.

Change this.shipWillExitWitchspace to this.systemWillPopulate to move the spawning functionality to a correct step. Do this change also to the neutering part to prevent script errors.

The only thing we need to change in this.$addSothis is replace "system.addShips("sothis", 1, [x, y, z]);" with a proper populator:

Code: Select all

		var exactPosition = [x, y, z];
		system.setPopulator("sothis_tc", {
			callback: function(pos) {			
				system.addShips("sothis", 1, pos, 0);					
			}.bind(this),
			location: "COORDINATES",
			coordinates: exactPosition,
			deterministic: true
		})

I cannot seem to find any of this code in any of the files in the 2017 Sothis Variant I have downloaded. Or in the 2013 variant. And, there seems to be no sothis_tc.js file.

Have I failed already?

Code: Select all

Sothis 2010, 2013, 2017


What’s in What
							2017		2013		2010
Oolite version available				1.84/6		1.76/7		just before 1.75,
											after 4 years of Ahruman's unstable releases

Folder & Files						2017		2013		2010

Readme.txt						yes		yes		yes

Config folder
-demoships.plist					yes		yes		yes
-script.js						yes		yes		yes
-shipdata.plist						yes		yes		yes
-Thumbs.db						no		yes		yes

Models folder
-sothdeco.dat						yes		yes		yes
-sothdock.dat						yes		yes		yes
-sothinner.dat						yes		yes		yes
-sothis.dat						yes		yes		yes
-sothmid.dat						yes		yes		yes
-sothorb.dot						yes		yes		yes
-sothouter.dat						yes		yes		yes

Scripts folder
-sothis-station-market.js				yes		no		no
-sothisscript.js					yes		yes		yes

Shaders folder
-kwsothishsaderf.fragment				yes		yes		yes
-kwsothisshaderv.vertex					yes		yes		yes

Textures folder
-oldsothis_normals.png					yes		yes		yes
-sothdeco_effects.png					yes		yes		yes
-sothdeco_lites.png					yes		yes		yes
-sothdeco_normals.png					yes		yes		yes
-sotchdeco_skin.png					yes		yes		yes
-sothdock_effects.png					yes		yes		yes
-sothdock_lites.png					yes		yes		yes
-sothdock_normals.png					yes		yes		yes
-sothdock_skin.png					yes		yes		yes
-sothis_buoy_effects.png				yes		yes		yes
-sothis_buoy_lites.png					yes		yes		yes
-sothis_buoy_normals.png				yes		yes		yes
-sothis_buoy_skin.png					yes		yes		yes
-sothis_effects.png					yes		yes		yes
-sothis_lites.png					yes		yes		yes
-sothis_normals.png					yes		yes		yes
-sothis_skin.png					yes		yes		yes


No requires.plist, no manifest.plist in any of the 3.

[spara]

Those are inside SothisTC. We're not touching the original Sothis at all, only overriding with an external oxp.

[andrax_iON]

Clearly, I'm doin' it wrong; with unedited Sothis_TC, I'm able to switch to the Sothis station on the ASC - after editing (and checking, and re-checking edits) I'm no longer able to dial in the station on exiting Zaonce.

Log :

<snip>

Edited sothis_tc.js :

<snip>

Best regards,
Clueless, of Zeta Crucis
8~/

update : I am a plank. "Change this.shipWillExitWitchspace to this.systemWillPopulate" & everything's fine.

*facepalm*

[spara]

When something goes south, check your log for clues. Is there something alarming in the log?

[andrax_iON]

Is there something alarming in the log?

Only my sticky fingers; I simply missed the requirement to update 'this.shipWillExitWitchspace' to 'this.systemWillPopulate'.

Confirmed that I can now save at the station.

Perhaps I should have removed the previous post, rather than edit. Let it be a monument to my stupidity.. *grin*

cheers!

[Cholmondely]

Those are inside SothisTC. We're not touching the original Sothis at all, only overriding with an external oxp.

Red Herring:

Are there larger versions of the trade route maps (c.200Kb each) from the SothisTC.oxp which I could use in the wiki?

I want to write a geography page for wiki (and possibly a trade routes page if I find enough material) and need a larger map which shows the trade routes clearly like the one in your .oxp. The only such map I've found so far is Capt Solo's - it has nice clear trade routes, but they are his own versions, not Presti's & Clym's.

By the way, having just discovered that the SothisTC is a completely different .oxp from the ones I had "discovered"/linked to on the first page, and having had a chance to poke about inside it - very, very nice! What a lovely idea for an .oxp! Ingenious!

[spara]

cheers!

You're welcome

Red Herring:
Are there larger versions of the trade route maps (c.200Kb each) from the SothisTC.oxp which I could use in the wiki?

Here is a link to the original G1 map: http://www.crimsonforge.co.uk/cloister/OOmap_G1.pdf. Change the name of the pdf to get the other sectors/galaxies.

Did you manage with the changes to the oxp? Can you now save at Sothis? Did you manage to tweak the positioning of the station?

Next step would be fixing the market. Do you want to be ambitious and create a market with some flavor or shall we just go with the standard market?

[montana05]

Next step would be fixing the market. Do you want to be ambitious and create a market with some flavor or shall we just go with the standard market?

Bold suggestion of mine, how about creating a new market similar to the rock hermits in the core ?