OXP Event handlers

[hiran]

So there are numerous event handling functions for world scripts (see World Script Event Handlers), but apart from that there seem to be ship scripts (see Ship Script Event Handlers).

Now I do not intend to create my own ship, so shipdata.plist tweaking won't help. Instead I'd like to attach my event handler to the player ship (and maybe some selected others). But how exactly does this work?

[Wildeblood]

So there are numerous event handling functions for world scripts (see World Script Event Handlers), but apart from that there seem to be ship scripts (see Ship Script Event Handlers).

Now I do not intend to create my own ship, so shipdata.plist tweaking won't help. Instead I'd like to attach my event handler to the player ship (and maybe some selected others). But how exactly does this work?

You spot a useful looking event in the list of Ship Script Event Handlers).
You write a function for it, and include it in a world script.
Test it. It will probably work.
If it's one of the rare ones that are only for non-player ships, it won't work. If so, come back to the BB and have a whinge about it.

Yes, I've had a look at that wiki page; there's a section at the bottom clearly labelled "NPC only". You can use all the events listed above that in world scripts. I suspect I've misunderstood your question, haven't I?

[hiran]

You spot a useful looking event in the list of Ship Script Event Handlers).
You write a function for it, and include it in a world script.
Test it. It will probably work.
If it's one of the rare ones that are only for non-player ships, it won't work. If so, come back to the BB and have a whinge about it.

Yes, I've had a look at that wiki page; there's a section at the bottom clearly labelled "NPC only". You can use all the events listed above that in world scripts. I suspect I've misunderstood your question, haven't I?

So I decided for this function: shipDumpedCargo
It is listed in Ship Event Handlers but not in World Event Handlers. Thus I added to my world script this content:

Code: Select all

this.shipDumpedCargo = function(cargo)
{
   log(this.name, "shipDumpedCargo(" + cargo + ")");
}

And indeed. I bought some cargo, launched and then dropped a pod. This is what I saw in the log:

Code: Select all

21:27:25.026 [oolite-starter-oxp]: shipDumpedCargo([Ship "Cargo container" position: (-44068.3, 60055.3, 438413) scanClass: CLASS_CARGO status: STATUS_IN_FLIGHT])

So if the world script can receive all the ship script events, why distinguish between them at all? Nevertheless, if this also works for the other events the question is answered.

[phkb]

The worldscript event handles events for the player ship. If you want to link up to the same event for any other ship, the code needs to be in a ship script.

[hiran]

The worldscript event handles events for the player ship. If you want to link up to the same event for any other ship, the code needs to be in a ship script.

Ok, that is a difference.
How would I, from one OXP, hook a ship script onto some other ship?

[Wildeblood]

How would I, from one OXP, hook a ship script onto some other ship?

You need some reference to the ship, e.g. player.ship.target, then you can read its script at player.ship.target.script, or replace it entirely using player.ship.target.setScript("hiran-ship-script.js")

https://wiki.alioth.net/index.php/Oolit ... #setScript

Says, in its entirety, the following:

function setScript(scriptName : String)
Set, or completely replace, the javascript code associated to a ship entity.

[hiran]

player.ship.target.setScript("hiran-ship-script.js")

How do I get that script name? Is it the filename? Relative to my OXP root? What if I need subdirectories? And then think of subdirectories in Windows and in Linux...

[Wildeblood]

player.ship.target.setScript("hiran-ship-script.js")

How do I get that script name? Is it the filename? Relative to my OXP root? What if I need subdirectories? And then think of subdirectories in Windows and in Linux...

JS files go into the "Scripts" sub-directory of your OXP. The file world-scripts.plist in "Config" lists scripts to be copied into the "worldScripts" namespace at start up, the other files sit there patiently waiting to be used as ship scripts, equipment scripts, etc.

All the OXPs are merged at load. All the JS files in any subdirectory named "Scripts" go into one big pool. (Similarly, all the PNG files in any "Images" directory, etc.) This allows your OXP to use resources from other OXPs. That's why it's important to prefix filenames with something unique (not "oolite-") to avoid naming conflicts. Then you just use the filename, you don't need to worry about the full path.

[Wildeblood]

You need some reference to the ship, e.g. player.ship.target

I once used player.ship.target.target to check if another ship was targeting me, then if it wasn't, player.ship.target.target.target to check if its target was targeting me (which would imply my target was helping me, and would be silly to shoot at.)
This sort of thing amuses me. I don't know whether player.ship.target.target.target.target works*, but I assume it does. I can't think what it would be good for.

* i.e. Whether there is some limit in javascript as to how long such a daisy chain of object references can get.

[MrFlibble]

All the OXPs are merged at load. All the JS files in any subdirectory named "Scripts" go into one big pool. (Similarly, all the PNG files in any "Images" directory, etc.) This allows your OXP to use resources from other OXPs. That's why it's important to prefix filenames with something unique (not "oolite-") to avoid naming conflicts. Then you just use the filename, you don't need to worry about the full path.

I'm having a senior moment attempting to grok that!!

Why files not referenced in the pool by e.g. bigship.png (my oxp 'bigship.png') and when not in the current, something like com.flibble.dodgyoxp1.bigship.png, an unimaginatively named png file in another but specific oxp?

In my head, I'm imagining OXP authors (attempting to observe due-diligence) having to grep the file-lists of ALL the available other OXP's in an expanding Ooniverse in order to avoid filename clashes. (explosion.png, texture.png, should-I-prefix-all-filenames-with-a-UUID-to-avoid-mayhem.png)

I feel like I missed a sanity clause, and it's not even Christmas.

[Wildeblood]

All the OXPs are merged at load. All the JS files in any subdirectory named "Scripts" go into one big pool. (Similarly, all the PNG files in any "Images" directory, etc.) This allows your OXP to use resources from other OXPs. That's why it's important to prefix filenames with something unique (not "oolite-") to avoid naming conflicts. Then you just use the filename, you don't need to worry about the full path.

I'm having a senior moment attempting to grok that!!

Why files not referenced in the pool by e.g. bigship.png (my oxp 'bigship.png') and when not in the current, something like com.flibble.dodgyoxp1.bigship.png, an unimaginatively named png file in another but specific oxp?

In my head, I'm imagining OXP authors (attempting to observe due-diligence) having to grep the file-lists of ALL the available other OXP's in an expanding Ooniverse in order to avoid filename clashes. (explosion.png, texture.png, should-I-prefix-all-filenames-with-a-UUID-to-avoid-mayhem.png)

I feel like I missed a sanity clause, and it's not even Christmas.

1. A cocoanut fell on my head recently, so maybe I'm mis-remembering, but:
2. If I am remembering correctly, "I didn't do it!"
3. I notice worldscripts nowadays have a unique ID prepended to them (it was not so back in my day), but to access one from another we still use its "name" property, which must be unique.

Addendum:
I've been sitting here tying to think of words to back-pedal, but... no. That's how I remember it working. We'll just have to await someone more knowledgeable.

[phkb]

In my head, I'm imagining OXP authors (attempting to observe due-diligence) having to grep the file-lists of ALL the available other OXP's in an expanding Ooniverse in order to avoid filename clashes. (explosion.png, texture.png, should-I-prefix-all-filenames-with-a-UUID-to-avoid-mayhem.png)

Yes.

Or you just create a prefix for all your files, and you should be 99.9% OK. The 0.1% will be extremely rare (somehow having two OXP's use the same prefix and then the same filename is *possible*, but highly unlikely).

JS files go into the "Scripts" sub-directory of your OXP. The file world-scripts.plist in "Config" lists scripts to be copied into the "worldScripts" namespace at start up, the other files sit there patiently waiting to be used as ship scripts, equipment scripts, etc.

The missing detail here are the "script.js" files in the Config folder. There are literally hundreds of OXP's with this configuration. *In this instance*, each script.js file is kept unique (ie they do not overwrite eachother), and is automatically added to the worldscripts JS pile without needing to use the world-script.plist file.