Difference between revisions of "Oolite JavaScript Reference: Manifest"

From Elite Wiki
m (→‎Behaviour notes: updated link)
 
(19 intermediate revisions by 7 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>''' provides direct access to 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).
−
 
 
−
Awarding the player with extra 10 tons of food can be done in different ways:
 
−
Manifest.food += 10;
 
−
or
 
−
player.ship.manifest.food += 10;
 
−
or
 
−
Manifest["food"] += 10;
 
−
 
 
−
If there were less than 10 tons of cargo space available, any extra cargo is silently discarded.
 
  
 
=== <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''' (or '''liquorWines'''): 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).
−
Access the '''liquor/wines''' quantity on the hold via either
+
 
−
Manifest["liquor/wines"]
+
'''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.'''
−
or
 
−
Manifest.liquorWines
 
  
 
=== <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''' (or '''gemStones'''): 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.
−
Access to the '''gem-stones''' property is via
 
−
Manifest["gem-stones"]
 
−
or
 
−
Manifest.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''' (alternative name '''alienItems'''): Integer (read/write)
+
 
−
Quantity of alien items in the players ship.<br>
+
=== <code>alien_items</code> ===
−
Access the '''alien items''' property either via
+
  '''alien_items''' : Number (read/write integer)
−
Manifest["alien items"]
+
The quantity of alien items in the ship’s hold.
−
or
+
 
−
Manifest.alienItems
+
'''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 objects. Each object contains the info for a commodity present in the player's hold:
+
Array of objects. Each object contains information for a commodity present in the player’s hold:
−
  commodity : String (corresponds to manifest["commodity"])
+
  commodity : String (the name of the corresponding property)
−
  quantity : Integer
+
containers: Number (integer) - 1.79 or later
 +
  quantity : Number (integer)
 
  displayName : String (commodity display name, can be different for different languages)
 
  displayName : String (commodity display name, can be different for different languages)
−
  unit : String ('t' = tons, 'kg' = kilograms, 'g' = grams)
+
  unit : String (“t”, “kg” or “g”)
  
−
Example usages of the manifest.list property
+
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;
 
  var i, m;
 
   
 
   
 
  // for certain types of cargo (like gem-stones) player.ship.cargoSpaceUsed can still be 0
 
  // for certain types of cargo (like gem-stones) player.ship.cargoSpaceUsed can still be 0
−
  // even if we're carrying 100 or more.
+
  // even if we’re carrying 100 or more.
−
  log('The player is currently carrying ' + (manifest.list.length > 0 ?'the following:' : 'nothing.'))
+
  log("The player is currently carrying " + (manifest.list.length > 0 ? "the following:" : "nothing."))
 
   
 
   
−
  for (i = 0; i<manifest.list.length;i++)
+
  for (i = 0; i < manifest.list.length; i++)
 
  {
 
  {
−
  m = manifest.list[i];
+
    m = manifest.list[i];
−
  log( m.quantity + m.unit + ' of '+ m.displayName );
+
    log( m.quantity + " " + m.unit + " of "+ m.displayName );
 
  }
 
  }
 
and
 
and
 
  var i, c;
 
  var i, c;
 
   
 
   
−
  // now remove at least ''1 of / 20% of'' each type of cargo carried.
+
  // now remove ''at least 1 of / 20% of'' each type of cargo carried.
−
  for (i = 0; i<manifest.list.length;i++)
+
  for (i = 0; i < manifest.list.length; i++)
 
  {
 
  {
 
  c = manifest.list[i].commodity;
 
  c = manifest.list[i].commodity;
−
  manifest[c] = Math.floor(manifest[c] * .8);
+
  manifest[c] = Math.floor(manifest[c] * 0.8);
 
  }
 
  }
  
−
[[Category:Oolite scripting]]
+
=== 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
 +
Returns the current long text comment for the named commodity as shown on the individual commodity (F8F8) screen.
 +
 
 +
=== setComment ===
 +
{{oolite-method-added|1.81}}
 +
function '''setComment'''(commodity : String, comment : String) : Boolean
 +
Sets a long text comment for the named commodity as shown on the individual commodity (F8F8) screen.  Returns <code>false</code> on failure such as specifying an unrecognized commodity.
 +
 
 +
=== setShortComment ===
 +
{{oolite-method-added|1.81}}
 +
function '''setShortComment'''(commodity : String, comment : String) : Boolean
 +
Sets a short text comment for the named commodity as shown on the market (F8) screen.  Returns <code>false</code> on failure such as specifying an unrecognized commodity.
 +
 
 +
=== shortComment ===
 +
{{oolite-method-added|1.81}}
 +
function '''shortComment'''(commodity : String) : String
 +
Returns the current short text comment for the named commodity as shown on the market (F8) screen.
 +
 
 +
 
 +
 
 +
 
 +
 
 +
[[Category:Oolite JavaScript Reference]]

Latest revision as of 19:49, 23 October 2022

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

Returns the current long text comment for the named commodity as shown on the individual commodity (F8F8) screen.

setComment

This method was added in Oolite test release 1.81. 

function setComment(commodity : String, comment : String) : Boolean

Sets a long text comment for the named commodity as shown on the individual commodity (F8F8) screen. Returns false on failure such as specifying an unrecognized commodity.

setShortComment

This method was added in Oolite test release 1.81. 

function setShortComment(commodity : String, comment : String) : Boolean

Sets a short text comment for the named commodity as shown on the market (F8) screen. Returns false on failure such as specifying an unrecognized commodity.

shortComment

This method was added in Oolite test release 1.81. 

function shortComment(commodity : String) : String

Returns the current short text comment for the named commodity as shown on the market (F8) screen.

Retrieved from "https://wiki.alioth.net/index.php?title=Oolite_JavaScript_Reference:_Manifest&oldid=76156"