Adding ships - I don’t get it.

[JensAyton]

Very definitely JavaScript.

The JS documentation on the wiki is current and reflects what’s in the development build, and what will soon be in 1.68. This thread is about working out how to do things in 1.69.

[Arexack_Heretic]

Good point there.
I did not know that.
Java-script it is then.

Just browsing the documentation there....

---
maybe to simplify the addSystemShips/addShips methods, we could define 'volumes', defining allowed placement coordinates.

AddShips (Volume, role, number)

Volume is Aegis, Sun, Planet, Route1, Route2 or another custom (pre-)defined volume.

Maybe there is also a way to add and subtract these volumes?
(the sun or planet volumes should have a maximum diameter, but also a minimum, defined by planet/sun_radius + 10000.)

addShipsWithinRadius would still be handy to define 'on the fly' volumes.

--

Also an added argument to define whether a role or entitykey is called for by the method may be better than having two duplications of the methods.
But I'm conflicted about that. Duplicate methods may be less complicated.
edit: yeah, more arguments would make things only difficult.
I propose AddShips and AddEntities.

[JensAyton]

Note to myself when implementing this: request from LittleBear:

This isn't really a priority but if its easy to add could we have an spawnShipWithCloud type command, so that when a ship is added it emerges from a Hyperspace cloud? I've been sitting at the witch point a lot playtesting and other ships entering the system look really cool as the emergy from their entry cloud. Somthimes in a script you want to call ships to a position as if they've just jump in. Although you can do this with an addships they then just pop into existance, which looks a bit odd if the player is there to observe it.

[Commander McLane]

This isn't really a priority but if its easy to add could we have an spawnShipWithCloud type command, so that when a ship is added it emerges from a Hyperspace cloud? I've been sitting at the witch point a lot playtesting and other ships entering the system look really cool as the emergy from their entry cloud. Somthimes in a script you want to call ships to a position as if they've just jump in. Although you can do this with an addships they then just pop into existance, which looks a bit odd if the player is there to observe it.

Uhmm? I always thought that's exactly what script-added ships (with any addShips-method) do: pop out of a hyperspace cloud. Or why do I see huge blue rings when e.g. a thargoid carrier appears at the witchpoint?

[Ramirez]

I think you're right but there might be the odd occasion where you need to spawn a ship in an unpredictable location, and so the coordinate-based addShips functions aren't suitable. Certainly in the Trident Down script I have ships coming to the player's rescue as if from witchspace, but all I can do is spawn them and so they appear from nowhere.

[Commander McLane]

I think you're right but there might be the odd occasion where you need to spawn a ship in an unpredictable location, and so the coordinate-based addShips functions aren't suitable. Certainly in the Trident Down script I have ships coming to the player's rescue as if from witchspace, but all I can do is spawn them and so they appear from nowhere.

In JS you can do it with system.legacy_addShipsAt(role, number, "abs", player.ship.position) without using spawn (if that is what keeps the hyperspace cloud from showing).

Or with system.legacy_addShipsWithinRadius(role, number, "abs", player.ship.position, suitableDistance), which is precisely what the "Create ship..."-option in Debug-menu does.

[Commander McLane]

Okay, LittleBear is right.

Some testing reveals that the witchspace-exit cloud appears when addShips is used.

It does not appear when any other method of the family is used, namely addSystemShips, addShipsAt, addShipsAtPrecisely and addShipsWithinRadius.

And it certainly is not supposed to appear with spawn, because this method's special purpose is to replace one entity with another (like a ship with a model of its wreck). It wouldn't make sense to have the replacement pop out of witchspace.

At the end of the day this tells us that there are some subtle differences between the different methods of adding ships, which I didn't catch here. (Another one being that all methods requiring a coordinate-system (addShipsAt, addShipsAtPrecisely and addShipsWithinRadius) add their ships along the line witchpoint-planet (if "wpx" is the chosen system), whereas addSystemShips adds ships along a line witchpoint-station. Again a subtle difference, which means that addSystemShips is indeed not a special case of addShipsAt.)

*****

My suggestion for the true JS-implementation of adding ships would be to make the creation of the witchplace-exiting cloud an (optional) parameter of the calling method, defaulting to true. Then we could drop the equivalent to the current addShips as special case of the equivalent to the current addShipsAt. With another parameter for the grade of precision to the given coordinates we could unify the equivalents of the current addShipsAt and addShipsAtPrecisely to one method only, and have elegantly dropped two of the current five. Then we only have left to debate whether or not we want to retain the functionality of the current addSystemShips and its line between witchpoint and station. And how to realize the addition of a couple of ships in a given radius. (Perhaps just another optional parameter in a unified method.).

Already we would be down from five to only two different methods: system.addShipsAt(role, number, coordScheme, vector, [radius], [precision], [witchspace cloud]) and system.addSystemShips(role, number, fraction between wp and station, [radius], [precision], [witchspace cloud]) (why not the same three options?). (Method names subject to change by the authorities, of course.)

EDIT: And come to think of it, [precision] isn't actually needed, if we have already [radius], which all by itself gives control of the precision. So we can drop one of the parameters again, and end up with system.addShipsAt(role, number, coordScheme, vector, [radius], [witchspace cloud]).

The current spawnShip could be dropped altogether, because its only purpose (being able to set the orientation of the added entity) can be achieved better through a ship-script.

So of the old family only spawn is left, which is already a method of the Ship-class, and serves its own purpose.

The jungle of ship-adding methods would finally be gone.

[Commander McLane]

Have thought a little more about the integration of addSystemShips.

The only difference between addSystemShips and the other methods is that addSystemShips adds ships along a line witchpoint-station (as opposed to witchpoint-planet). But of course we can achieve this as well with a unified system.addShips() method in JavaScript, because the position of the station is known.

So legacy_addSystemShips(role, number, fraction between wp and station) would translate into addShipsAt(role, number, "abs", [fraction * x-component of mainStation.position, fraction * y-component of mainStation.position, fraction * z-component of mainStation.position], [radius], [witchspace cloud]).

To split the mainStation.position into its x, y, z-components should be doable via JS.

So in the end we would have only one method remaining.

I've put up these thoughts in a more consistent way on the System talk page on the wiki. Now it's up to the coders to do something with it.

[Eric Walch]

When you look into Vector3D you will see that there is already a function that does that:

Vector3D.interpolate(pos1, pos1, fraction) Or in this case: Vector3D.interpolate([0,0,0], System.mainStation.position, fraction) giving in your total:

Or with your example:
addShipsAt(role, number, "abs", Vector3D.interpolate([0,0,0], System.mainStation.position, fraction), [radius], [witchspace cloud]).

With the interpolate() you can set up any space lane between two objects. This info was already long on he wiki, but just last week I added a more explicit page to wiki about this interpolate(). I linked it from within the page that describes these addShip methods.

Again a subtle difference, which means that addSystemShips is indeed not a special case of addShipsAt.

There are more differences. When role is pirate or trader, it fills the cargo holds and sets a bounty for pirate. It also sends an AI message "EXITED_WITCHSPACE" for the AI to react upon.

[JensAyton]

Vector3D.interpolate(pos1, pos1, fraction) Or in this case: Vector3D.interpolate([0,0,0], System.mainStation.position, fraction) giving in your total:

Because the first vector is [0,0,0], this simplifies to system.mainStation.position.multiply(fraction).

[Commander McLane]

Again a subtle difference, which means that addSystemShips is indeed not a special case of addShipsAt.

There are more differences. When role is pirate or trader, it fills the cargo holds and sets a bounty for pirate. It also sends an AI message "EXITED_WITCHSPACE" for the AI to react upon.

Ah, some more differences formerly unknown to the non-coder. But why does addSystemShips do that? Shouldn't this be something for addShips?

Or, asked differently: would it hurt if all ship adding methods (read: the grand unified addShip() method) would do that?

[Eric Walch]

Ah, some more differences formerly unknown to the non-coder. But why does addSystemShips do that? Shouldn't this be something for addShips?

Of cause, I quoted the wrong passage of your text. The extras in addShips that internally calls the routine that specially was designed to add ships at the witchpoint. Therefor also the animation.

[Commander McLane]

Ah, some more differences formerly unknown to the non-coder. But why does addSystemShips do that? Shouldn't this be something for addShips?

Of cause, I quoted the wrong passage of your text. The extras in addShips that internally calls the routine that specially was designed to add ships at the witchpoint. Therefor also the animation.

So it could (for a start) be bound to the [witchspace cloud]-parameter, which probably could be renamed more properly to [exited witchspace]. Because the whole routine makes sense for ships which are supposed to come out of witchspace.

[JensAyton]

Given that there are a lot of permutations, and no-one wants a function with fifty parameters, I’m thinking the witchspace cloud might be a good place to split the function at: one addShips() (or possibly spawnShips()) for ships that pop out of nowhere, the conceptual inverse of ship.remove(), and one jumpInShips() for ships that jump in in an “in-story” way, the conceptual inverse of ship.explode(). They’d probably have the same list of parameters for count, positioning and so forth.

[Commander McLane]

Seems sensible. I'd say go for it!