Scripting requests

[JensAyton]

Please post specific requests for scripting functionality here, so we’ve got them in one place. Post a description rather than the desired method name, since a) a name that seems clear to you might not to me, and b) future scripting enhancements will primarily be for JavaScript.

Example proposal:
The ability to get and set a non-player ship’s scan class from within its AI script.

Edit: Fixed typo which completely reversed meaning.

[Arexack_Heretic]

-an effective way to "spawn" relative to a calling object-entity
Using a quaternion to determine facing direction, origin and axis are the same as the calling entity.

'shipcentric' x y z
facing direction: W X Y Z

Code: Select all

"spawnSpecifically: <role> x y z W X Y Z"

example:

a trapAI triggers on the player:
"scriptActionOnTarget: spawnSpecifically: pirate 0 250 2500 0 0 0 1"

This would hyperspaceIn a pirate + facing the player + slightly avove his plane of vision at 2.5 km distance.

--++=<>=++--

Code: Select all

remove_cargo: <type> <number>

disregarding negative results or setting them to zero should remove the need for a removeAllCargo: <type> method.
(4gems in hold, removeCargo: gems 6 = 0gems)
an oxp-er could just set removeCargo to a large number to get all cargo of a single type removed.

--++=<>=++--

a method to determine cargoInHold

Code: Select all

cargoInHold: <type>

returns: cargo_type_number value
type: as in commodities or 'all'.

example:

A ship has 2 tonnes of Food and one tonne of Computers.
the ships' AI or script checks the cargo with "cargoInHold: all" and this returns with the value <3>. While "cargoInHold: Food" would return <2>.

For the player, these values are all probably stored somewhere already and should be more readilly accesable by cargo_Food_number, cargo_Textiles_number, etc.

--++=<>=++--

I'd love to have the <key>name</key> $ in shipInfos accept [descriptions].

is this at all possible?
I'm not sure, whether the random selection of [descriptions] for a given ship could be stored. Probably not.

--++=<>=++--

Selectively overriding illegal_goods.plist
in planet.plist or script.plist or in a expanded illegal_goods.plist itself.

[Uncle Reno]

OK, apologies if I term any of this incorrectly but here goes.

1. A way of telling that the player is within the Aegis of a station i.e. STATUS_IN_STATIONAEGIS.

2. A way of displaying the players ships name in missiontext i.e.

Code: Select all

<string>That's a mighty fine [player_shipname] you've got there Commander [commander_name].</string>

I have looked for both of these but I can't find them in the Wiki.

[JensAyton]

2. A way of displaying the players ships name in missiontext i.e.

Code: Select all

<string>That's a mighty fine [player_shipname] you've got there Commander [commander_name].</string>

[commander_shipname]. There’s also [commander_rank] and [commander_legal_status], as well as %H for the system name, %I for system name + “ian”, and %R for random gibberish (as in “%R bless you!” in [thanks-for-assist], “%R! %R! %R!” in [thargoid_curses], and “%R! Leave now, or face Police retribution.” in [police-attack-warning]).

[JensAyton]

A mission screen object model for JavaScript, which allows different mission scripts to set up screens without risk of interfering with each other.

[dajt]

An object model for equipment.

Allow the quantity and prices of goods in the current system to be queried and updated.

Set the cargo of any ship in the system.

More methods for finding/targeting ships for use by both the player and the AI ships.

More options for playing sounds, including specifying the absolute or relative location of the sound.

[JensAyton]

For that matter, do we have an object model for ships/entities?

Code: Select all

var nearest = Universe.StationNearestEntity(Player);
if (nearest.EntityInAegisRange(Player))
{
    /* player is in aegis range of a station */
}
else
{
    /* player is in deep space */
}

[dajt]

I have added a page to the wiki to be used to define the object model that will be exposed to the JavaScript interpreter.

See it at http://wiki.alioth.net/index.php/Oolite ... cification.

[CaptKev]

dajt, on the wiki for class Vessel you had the comment "need to represent docking ports somehow", does that mean multiple docking ports per ship?

[JensAyton]

I think it means the scripting model should be able to handle multiple docking ports, in case the game eventually does. :-)

[JensAyton]

dajt: as I recall, JS is prototype-based, not inheritance-based, but I take it that Vessel will have all the properties Entity has, and Player will have all the properties Vessel has?

This touches on the refactoring I’m planning, though. I feel that things like cargo canisters and missiles shouldn’t be ships, but should share a superclass with them. Vessel seems as good a name as any. I’m split between leaving station as a subclass of ship, or having both be subclasses of DockableVessel.

Other stuff to add to the model: Galaxy, System, Sun, Planet, Moon. Sun, Planet and Moon would all be types of CelestialBody. A Galaxy would have an array of Systems; a System would have arrays of Suns, Planets, Moons and Stations.

[dajt]

CaptKev: Like Ahrurman said, to allow for the possibility of multiple docking ports in future ;)

Ahruman: Yes, JS is prototype based but I am using an inheritence-type syntax as a short-cut to express things like Vessel will have all the properties and methods of Entity. JS supports "class" methods and properties as well as "instance" methods and properties which is why there is at least one "static" in there.

[Commander McLane]

Thanks, Ahruman, for this thread, and for taking on the task of giving us new methods for scripting! Also thanks for the informations about [commander_shipname], [commander_rank] and [commander_legal_status]! Didn't know those before. And especially the last one comes in quite handy for Anarchies.oxp.

Occasionally in various threads I have already posted a couple of my wishes, just as they occured to me and I would have liked to script. I try to recall them all. So here comes an extended cargo bay full of requests (I apologize for the sheer amount, but I have had quite some wishes indeed):

1. removeCargo: <amount> <Commodity name> as an inverse of awardCargo. If the amount of cargo becomes negative by this method it should be set to 0. That's the same method Arexack_Heretic already mentioned in his post above, but I suggest the syntax with the capital C instead of the underscore, because of the similarity to other methods of this kind (like awardCargo).

2. I am in total agreement to A_H's request for a method of querying the cargo in hold. cargoInHold: with all the possible return-values would be cool.

3. If that shouldn't be possible I at least would like to have three querying states: cargo_number as the amount of cargo currently carried by the player ship, cargoFreespace_number as the amount of cargospace not yet filled and cargoCapacity_number as the total amount of cargo that can be carried by the player ship in its current configuration. Even two of these would be sufficient, because cargo_number + cargoFreespace_number = cargoCapacity_number, but to have all three would be more comfortable. With these methods it would be possible to script a bulk-transport.oxp: if cargoCapacity_number < 100 then missionscreen: "Sorry, Commander. If you want to get this mission you first have to get yourself a bigger ship."

4. A method for in- and decrementing the ship's clock. Like adjustClock: <amount> <interval>. <amount> would be an integer, positive for moving the clock forward, negative for moving it backward, <interval> is one of the following: "seconds", "minutes", "hours" or "days". Example: adjustClock: 20 minutes would do the same that is happening every time you are docking by hitting shift-D, and it could create the illusion that something you did according to a mission screen actually took some time. adjustClock: -4 hours could reverse the effect that installing any piece of equipment makes the clock advance (the installation of a Q-mine takes quite some time!). For scripted equipments this period can not yet be adjusted in the script (at least I wouldn't know how), so it can very likely be much too long.

5. More mathematical operators, namely for multiplication and division. multiply: <mission_variable> <value> would set mission_variable to mission_variable * value. divide: <mission_variable> <value> would do the opposite. Example: divide: mission_legal_status 2 would divide mission_legal_status by 2. The results could be rounded to an integer (like Oolite does to determine the number of energy bars from a ship's max_energy, through a division by 64 and killing everything after the point). If it's not rounded automatically, then also add round: <mission_variable>.

6. A method to determine where the player is witchspacing to, before he has arrived there, so that scripted changes can be made to the target system on STATUS_ENTERING_WITCHSPACE already. This is the only way to replace the main station and perhaps to change some other values as well in the system the player is jumping to. selectedPlanet_number could return the number of the planet currently selected on the galaxy chart and would do the trick.

7. Another new status_string: STATUS_IN_HYPERSPEED instead of STATUS_IN_FLIGHT as long as "J"-speed is activated. The engine must already be able to determine that, but we can't query it.

8. Another new method of creating ships relative to the calling entity: spawnWithinRadius: <role> <number> <radius in metres> should be available as AI-method and as a scripted action (like setup_actions or death_actions) in shipdata. So a station with spawnWithinRadius: asteroid 25 10000 in its setup_actions would sit in a small asteroid field, regardless where it would be spawned itself.

9. And another method for shipdata.plist: scavenger_role would work like defense_ship_role. And why not miner_role as well? These are the basic ship types that can be launched by a station's AI. We can control which ships are used as its defense. Why not the others as well?

After this wishlist of methods I would like to add the request for a new way of handling methods in a script and a new class of variables:

10. A loop structure. I don't know if that is possible, but sometimes I would have found it very useful. I can imagine a "while"-syntax:

Code: Select all

	{
		while = (
			"mission_legal_status greaterthan 0"
		);
		do = (
			"awardCredits: -10",
			"decrement: mission_legal_status"
		);
	},

The catch is that the loop would have to halt the script. It would be of no use if the engine would run the loop only once every ten seconds, like the rest of the script. So the loop would have to be completed before the next condition is checked.

11. Together with a loop it would be very nice to have arrays as a new kind of variables. Example: A_H proposed a complete redo of the in-game legal system in the course of the Anarchies.oxp-thread (see especially this post). He wanted to implement a local legal rating in each planet of the galaxy the player is currently in. For that he needed 256 different variables of the type: mission_variable_localrep_n, where n is a number from 0..255. Obviously an array would be the elegant solution to the problem of having to deal with 256 variables all the time. So my request is for <mission_variable> (<index>) as a new type of variable. <index> could be a value, another mission_variable or a querying state like planet_number.

The array-variable and the loop together would form a powerful team.

And I have got a last request in this round, which is not for a new method, but for correcting what I see as a bug in the engine:

12. Allow escorts to have custom AIs. As for now every entity that is called as an escort--be it by the engine itself or be it by assigning a shiptype or a specific ship to another entity as an escort in shipdata and setting it up in the caller's AI--will have escortAI and only escortAI, regardless of the ai_type method in its shipdata-entry. That shouldn't be so. The engine should prefer the AI specified in shipdata, and only resort to escortAI as a default if no other AI is specified in shipdata.

[Arexack_Heretic]

5) IIRC the JAVA-scripting extension already gives this freedom.

[JensAyton]

[lots of stuff]

Almost none of that will be done in the old scripting model. Equivalents to most of it will be in the JavaScript model, either from the start or over time.

Again, please post in terms of what you need to do, not how you think you’d like to do it in the old model.