Difference between revisions of "Oolite JavaScript Reference: Manifest"

From Elite Wiki
(Added Manifest page)
 
(added notes about pre-1.82 aliases for liquor_wines, gem_stones and alien_items)
 
(14 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 
<small>'''Prototype:''' <code>Object</code></small><br />
  
<small>'''Prototype:''' <code>Object</code></small><br />
  +
<small>'''Subtypes:''' none</small>
   
−
{{Oolite-class-added|1.74}}
  
  +
'''<code>Manifest</code>''' provides direct access to the cargo carried by the player.
  +
  +
Except <code>[[#list|list]]</code>, each property is an integer representing the quantity of a certain commodity. The units depend on the commodity, just as on the trading screen.
  +
  +
=== Behaviour notes ===
  +
When increasing a commodity, extra cargo beyond the ship’s capacity is discarded silently. For example, if the ship has 6 t of space available, and you add 10 to <code>player.ship.manifest.food</code>, only 6 t of food will be awarded.
  +
  +
For gold and platinum, 500 kg or more rounds up to 1 t, below 500 kg counts as 0 t in [[Oolite JavaScript Reference: Ship#cargoSpaceAvailable|cargo space]] calculations. This means a script can add up to 499 kg of gold or platinum into a nominally full hold. (The player himself can buy unlimited quantities at the market screen.) In the same way, 500 000 g of gemstones is rounded up to 1 t. (If you feel tempted to award the player half a tonne of gemstones, keep in mind that one can only sell up to 127 units of a commodity at a given station using the trading screen.)
  +
  +
Example:
  +
if (player.ship.[[Oolite JavaScript Reference: Ship#cargoSpaceAvailable|cargoSpaceAvailable]] >= 10)
  +
{
  +
player.ship.manifest.food += 10;
  +
}
  +
  +
=== Cargo marshalling ===
  +
When a player launches, all cargo from the manifest is loaded in cargo pods with the role “1t-cargopod”. This has some consequences for handling g and kg commodities when in flight:
  +
  +
* Every full t of such an article that the player has is put in a barrel on launch and consumes 1 t cargo space.
  +
* Every barrel that the player scoops takes one t of cargo space even when the content is far less in weight.
  +
* Every time cargo is added by script, the added amount is added to the hold in one or more 1 t cargo pods.
  +
* Every time the cargo is reduced, it is removed from one of the barrels. When the barrel becomes empty in the process, the barrel is removed.
  +
  +
On docking all barrels are unloaded and the manifest becomes just a list of goods. The manifest can be handled the same way when docked as when in flight, but the behaviour described above explains why the hold fills up fast when adding several small quantities of g/kg commodities by script.
   
−
'''<code>Manifest</code>''' objects provide information about the cargo carried by the player.
  
   
 
== Properties ==
  
== Properties ==
 
=== <code>food</code> ===
  
=== <code>food</code> ===
−
'''food''' : Integer (read/write)
 +
'''food''' : Number (read/write integer)
−
Quantity of food in the players ship.
 +
The quantity of food in the ship’s hold (t).
   
 
=== <code>textiles</code> ===
  
=== <code>textiles</code> ===
−
'''textiles''' : Integer (read/write)
 +
'''textiles''' : Number (read/write integer)
−
Quantity of textiles in the players ship.
 +
The quantity of textiles in the ship’s hold (t).
   
 
=== <code>radioactives</code> ===
  
=== <code>radioactives</code> ===
−
'''radioactives''' : Integer (read/write)
 +
'''radioactives''' : Number (read/write integer)
−
Quantity of radioactives in the players ship.
 +
The quantity of radioactives in the ship’s hold (t).
   
 
=== <code>slaves</code> ===
  
=== <code>slaves</code> ===
−
'''slaves''' : Integer (read/write)
 +
'''slaves''' : Number (read/write integer)
−
Quantity of slaves in the players ship.
 +
The quantity of slaves in the ship’s hold (t).
   
−
=== <code>liquor/wines</code> ===
 +
=== <code>liquor_wines</code> ===
−
'''liquor/wines''' : Integer (read/write)
 +
'''liquor_wines''' : Number (read/write integer)
−
Quantity of liquor/wines in the players ship.<br>
 +
The quantity of liquor/wines in the ship’s hold (t).
−
(Other allowed spellings for this property are: '''liquor_wines''' and '''liquorWines'''
 +
  +
'''Before Oolite 1.82, <code>liquor</code>, <code>wines</code> and <code>liquorWines</code> were aliases for this property. OXPs created before Oolite 1.82 may need to be updated to use <code>liquor_wines</code> instead.'''
   
 
=== <code>luxuries</code> ===
  
=== <code>luxuries</code> ===
−
'''luxuries''' : Integer (read/write)
 +
'''luxuries''' : Number (read/write integer)
−
Quantity of luxuries in the players ship.
 +
The quantity of luxuries in the ship’s hold (t).
   
 
=== <code>narcotics</code> ===
  
=== <code>narcotics</code> ===
−
'''narcotics''' : Integer (read/write)
 +
'''narcotics''' : Number (read/write integer)
−
Quantity of narcotics in the players ship.
 +
The quantity of narcotics in the ship’s hold (t).
   
 
=== <code>computers</code> ===
  
=== <code>computers</code> ===
−
'''computers''' : Integer (read/write)
 +
'''computers''' : Number (read/write integer)
−
Quantity of computers in the players ship.
 +
The quantity of computers in the ship’s hold (t).
   
 
=== <code>alloys</code> ===
  
=== <code>alloys</code> ===
−
'''alloys''' : Integer (read/write)
 +
'''alloys''' : Number (read/write integer)
−
Quantity of alloys in the players ship.
 +
The quantity of alloys in the ship’s hold (t).
   
 
=== <code>firearms</code> ===
  
=== <code>firearms</code> ===
−
'''firearms''' : Integer (read/write)
 +
'''firearms''' : Number (read/write integer)
−
Quantity of firearms in the players ship.
 +
The quantity of firearms in the ship’s hold (t).
   
 
=== <code>furs</code> ===
  
=== <code>furs</code> ===
−
'''furs''' : Integer (read/write)
 +
'''furs''' : Number (read/write integer)
−
Quantity of furs in the players ship.
 +
The quantity of furs in the ship’s hold (t).
   
 
=== <code>minerals</code> ===
  
=== <code>minerals</code> ===
−
'''minerals''' : Integer (read/write)
 +
'''minerals''' : Number (read/write integer)
−
Quantity of minerals in the players ship.
 +
The quantity of minerals in the ship’s hold (t).
   
 
=== <code>gold</code> ===
  
=== <code>gold</code> ===
−
'''gold''' : Integer (read/write)
 +
'''gold''' : Number (read/write integer)
−
Quantity of gold in the players ship.
 +
The quantity of gold in the ship’s hold (kg).
   
 
=== <code>platinum</code> ===
  
=== <code>platinum</code> ===
−
'''platinum''' : Integer (read/write)
 +
'''platinum''' : Number (read/write integer)
−
Quantity of platinum in the players ship.
 +
The quantity of platinum in the ship’s hold (kg).
   
−
=== <code>gem-stones</code> ===
 +
=== <code>gem_stones</code> ===
−
'''gem-stones''' : Integer (read/write)
 +
'''gem_stones''' : Number (read/write integer)
−
Quantity of gem-stones in the players ship.<br>
 +
The quantity of gem-stones in the ship’s hold. 500000 g and more counts as 1 ton in [[Oolite JavaScript Reference: Ship#cargoSpaceAvailable|cargoSpace]] calculations.
−
(Other allowed spellings for this property are: '''gem_stones''' and '''gemStones'''
  
   
−
=== <code>alien items</code> ===
  
  +
'''Before Oolite 1.82, <code>gemStones</code> was an alias for this property. OXPs created before Oolite 1.82 may need to be updated to use <code>gem_stones</code> instead.'''
−
'''alien items''' : Integer (read/write)
  
  +
−
Quantity of alien items in the players ship.<br>
  
  +
=== <code>alien_items</code> ===
−
(Other allowed spellings for this property are: '''alien_items''' and '''alienItems'''
  
  +
'''alien_items''' : Number (read/write integer)
  +
The quantity of alien items in the ship’s hold.
  +
  +
'''Before Oolite 1.82, <code>alienItems</code> was an alias for this property. OXPs created before Oolite 1.82 may need to be updated to use <code>alien_items</code> instead.'''
   
 
=== <code>list</code> ===
  
=== <code>list</code> ===
 
'''list''' : Array (read-only)
  
'''list''' : Array (read-only)
−
Array of dictionaries. Each dictionary contains the info for a commodity that is in the players hold:
 +
Array of objects. Each object contains information for a commodity present in the player’s hold:
−
commodity : String
 +
commodity : String (the name of the corresponding property)
−
quantity : Integer
 +
containers: Number (integer) - 1.79 or later
−
commodityName : String (= display-name, can be different for different languages)
 +
quantity : Number (integer)
−
unit : String ('t' = tons, 'kg' = kilograms, 'g' = grams)
 +
displayName : String (commodity display name, can be different for different languages)
  +
unit : String (“t”, “kg” or “g”)
  +
  +
Quantity is the number of units of cargo carried; containers is the number of TC containers this takes up. For the sub-tonne commodities these numbers are likely to be significantly different, and no containers are used while the ship is docked.
  +
  +
'''Examples:'''
  +
var i, m;
  +
  +
// for certain types of cargo (like gem-stones) player.ship.cargoSpaceUsed can still be 0
  +
// even if we’re carrying 100 or more.
  +
log("The player is currently carrying " + (manifest.list.length > 0 ? "the following:" : "nothing."))
  +
  +
for (i = 0; i < manifest.list.length; i++)
  +
{
  +
m = manifest.list[i];
  +
log( m.quantity + " " + m.unit + " of "+ m.displayName );
  +
}
  +
and
  +
var i, c;
  +
  +
// now remove ''at least 1 of / 20% of'' each type of cargo carried.
  +
for (i = 0; i < manifest.list.length; i++)
  +
{
  +
c = manifest.list[i].commodity;
  +
manifest[c] = Math.floor(manifest[c] * 0.8);
  +
}
  +
  +
=== Extra properties ===
  +
  +
If an OXP defines a new trade good with key "xxx" then <code>manifest.xxx</code> will work for that good as it does for the built-in trade goods.
  +
  +
== Methods ==
  +
  +
=== comment ===
  +
{{oolite-method-added|1.81}}
  +
function '''comment'''(commodity : String) : String
  +
Return the current long text comment for the named commodity, shown on the F8 F8 screen.
  +
  +
=== setComment ===
  +
{{oolite-method-added|1.81}}
  +
function '''comment'''(commodity : String, value : String) : String
  +
Set the long text comment for the named commodity, shown on the F8 F8 screen.
  +
  +
=== setShortComment ===
  +
{{oolite-method-added|1.81}}
  +
function '''comment'''(commodity : String, value : String) : String
  +
Set the short text comment for the named commodity, shown in the optional column on the F8 screen.
  +
  +
=== shortComment ===
  +
{{oolite-method-added|1.81}}
  +
function '''shortComment'''(commodity : String) : String
  +
Return the current short text comment for the named commodity, shown in the optional column on the F8 screen.
  +
  +
   
−
e.g. Awarding the player with 10 tons of food can be achieved with:
  
−
Manifest.food += 10;
  
−
or
  
−
playerShip.manifest.food += 10;
  
−
or
  
−
Manifest["food"] += 10;
  
   
−
== Static methods ==
  
−
=== <code>toString</code> ===
  
−
function '''toString'''() : String
  
−
(Unfinished yet)
  
   
−
[[Category:Oolite scripting]]
 +
[[Category:Oolite JavaScript Reference]]

Latest revision as of 19:07, 16 June 2020

Prototype: Object
Subtypes: none

Manifest provides direct access to the cargo carried by the player.

Except list, each property is an integer representing the quantity of a certain commodity. The units depend on the commodity, just as on the trading screen.

Behaviour notes

When increasing a commodity, extra cargo beyond the ship’s capacity is discarded silently. For example, if the ship has 6 t of space available, and you add 10 to player.ship.manifest.food, only 6 t of food will be awarded.

For gold and platinum, 500 kg or more rounds up to 1 t, below 500 kg counts as 0 t in cargo space calculations. This means a script can add up to 499 kg of gold or platinum into a nominally full hold. (The player himself can buy unlimited quantities at the market screen.) In the same way, 500 000 g of gemstones is rounded up to 1 t. (If you feel tempted to award the player half a tonne of gemstones, keep in mind that one can only sell up to 127 units of a commodity at a given station using the trading screen.)

Example: 

if (player.ship.cargoSpaceAvailable >= 10)
{
    player.ship.manifest.food += 10;
}

Cargo marshalling

When a player launches, all cargo from the manifest is loaded in cargo pods with the role “1t-cargopod”. This has some consequences for handling g and kg commodities when in flight:

  • Every full t of such an article that the player has is put in a barrel on launch and consumes 1 t cargo space.
  • Every barrel that the player scoops takes one t of cargo space even when the content is far less in weight.
  • Every time cargo is added by script, the added amount is added to the hold in one or more 1 t cargo pods.
  • Every time the cargo is reduced, it is removed from one of the barrels. When the barrel becomes empty in the process, the barrel is removed.

On docking all barrels are unloaded and the manifest becomes just a list of goods. The manifest can be handled the same way when docked as when in flight, but the behaviour described above explains why the hold fills up fast when adding several small quantities of g/kg commodities by script.


Properties

food

food : Number (read/write integer)

The quantity of food in the ship’s hold (t).

textiles

textiles : Number (read/write integer)

The quantity of textiles in the ship’s hold (t).

radioactives

radioactives : Number (read/write integer)

The quantity of radioactives in the ship’s hold (t).

slaves

slaves : Number (read/write integer)

The quantity of slaves in the ship’s hold (t).

liquor_wines

liquor_wines : Number (read/write integer)

The quantity of liquor/wines in the ship’s hold (t).

Before Oolite 1.82, liquor, wines and liquorWines were aliases for this property. OXPs created before Oolite 1.82 may need to be updated to use liquor_wines instead.

luxuries

luxuries : Number (read/write integer)

The quantity of luxuries in the ship’s hold (t).

narcotics

narcotics : Number (read/write integer)

The quantity of narcotics in the ship’s hold (t).

computers

computers : Number (read/write integer)

The quantity of computers in the ship’s hold (t).

alloys

alloys : Number (read/write integer)

The quantity of alloys in the ship’s hold (t).

firearms

firearms : Number (read/write integer)

The quantity of firearms in the ship’s hold (t).

furs

furs : Number (read/write integer)

The quantity of furs in the ship’s hold (t).

minerals

minerals : Number (read/write integer)

The quantity of minerals in the ship’s hold (t).

gold

gold : Number (read/write integer)

The quantity of gold in the ship’s hold (kg).

platinum

platinum : Number (read/write integer)

The quantity of platinum in the ship’s hold (kg).

gem_stones

gem_stones : Number (read/write integer)

The quantity of gem-stones in the ship’s hold. 500000 g and more counts as 1 ton in cargoSpace calculations.

Before Oolite 1.82, gemStones was an alias for this property. OXPs created before Oolite 1.82 may need to be updated to use gem_stones instead.

alien_items

alien_items : Number (read/write integer)

The quantity of alien items in the ship’s hold.

Before Oolite 1.82, alienItems was an alias for this property. OXPs created before Oolite 1.82 may need to be updated to use alien_items instead.

list

list : Array (read-only)

Array of objects. Each object contains information for a commodity present in the player’s hold: 

commodity : String (the name of the corresponding property)
containers: Number (integer) - 1.79 or later
quantity : Number (integer)
displayName : String (commodity display name, can be different for different languages)
unit : String (“t”, “kg” or “g”)

Quantity is the number of units of cargo carried; containers is the number of TC containers this takes up. For the sub-tonne commodities these numbers are likely to be significantly different, and no containers are used while the ship is docked.

Examples: 

var i, m;

// for certain types of cargo (like gem-stones) player.ship.cargoSpaceUsed can still be 0
// even if we’re carrying 100 or more.
log("The player is currently carrying " + (manifest.list.length > 0 ? "the following:" : "nothing."))

for (i = 0; i < manifest.list.length; i++)
{
    m = manifest.list[i];
    log( m.quantity + " " + m.unit + " of "+ m.displayName );
}

and 

var i, c;

// now remove at least 1 of / 20% of each type of cargo carried.
for (i = 0; i < manifest.list.length; i++)
{
	c = manifest.list[i].commodity;
	manifest[c] = Math.floor(manifest[c] * 0.8);
}

Extra properties

If an OXP defines a new trade good with key "xxx" then manifest.xxx will work for that good as it does for the built-in trade goods.

Methods

comment

This method was added in Oolite test release 1.81. 

function comment(commodity : String) : String

Return the current long text comment for the named commodity, shown on the F8 F8 screen.

setComment

This method was added in Oolite test release 1.81. 

function comment(commodity : String, value : String) : String

Set the long text comment for the named commodity, shown on the F8 F8 screen.

setShortComment

This method was added in Oolite test release 1.81. 

function comment(commodity : String, value : String) : String

Set the short text comment for the named commodity, shown in the optional column on the F8 screen.

shortComment

This method was added in Oolite test release 1.81. 

function shortComment(commodity : String) : String

Return the current short text comment for the named commodity, shown in the optional column on the F8 screen.

Retrieved from "http://backup.witchspacewiki.org/index.php?title=Oolite_JavaScript_Reference:_Manifest&oldid=58419"