Oolite JavaScript Reference: Market Scripts

Note: this page describes functionality currently only in the 1.81 development code. It may change further before being part of a stable release.

From Oolite 1.81 it is possible for Javascript to be used to modify station, system and trade good prices. It is possible that a single trade good price/quantity calculation may be affected by more than one script. The order of events in the calculation is as follows:

1. Firstly, the primary system market is calculated
   1. The trade good price and quantity are generated from the values in trade-goods.plist
   2. The updateGeneralCommodityDefinition handler of the commodity's market_script will be called to set primary market data for the trade good
   3. The updateLocalCommodityDefinition handler of the system's market_script will be called to modify primary market data for the trade good.
2. Secondary markets are then calculated for each non-main station
   1. The primary system market is copied into the secondary market, and then quantities are scaled to the station's market capacity
   2. If the station does not have a market script, the rules in its market_definition are applied.
   3. The updateGeneralCommodityDefinition handler of the commodity's market_script will be called again to set secondary market data for the trade good.
   4. The updateLocalCommodityDefinition handler of the station's market_script will be called to modify secondary market data for the trade good.

Handlers

updateGeneralCommodityDefinition

This method was added in Oolite test release 1.81.

function updateGeneralCommodityDefinition (goodDefinition : Object, station : Station, system : Int) : Object

This method takes an object containing the current good definition (keys as in trade-goods.plist, with an additional "price" key for the current price, "quantity" for the current quantity, and "key" for the identifier of the trade good in the plist), carries out modifications to it based on the station and system, and returns the object in the same format.

In general this method should only modify the "price", "quantity", "capacity", "legality_export" and "legality_import" keys of the goodDefinition object. Modifying other keys is possible but significant caution should be used when doing so.

This method is called for scripts defined for the trade good, and is applied once for each market that good appears at. It may be called twice for the same good - once with station = false to set the primary market, and once with station = (Station) for each secondary market. In general distinguishing between these two cases and performing different modifications will be necessary.

updateLocalCommodityDefinition

This method was added in Oolite test release 1.81.

function updateLocalCommodityDefinition (goodDefinition : Object, station : Station, system : Int) : Object

This method takes an object containing the current good definition (keys as in trade-goods.plist, with an additional "price" key for the current price, "quantity" for the current quantity, and "key" for the identifier of the trade good in the plist), carries out modifications to it based on the station and system, and returns the object in the same format.

In general this method should only modify the "price", "quantity", "capacity", "legality_export" and "legality_import" keys of the goodDefinition object. Modifying other keys is possible but significant caution should be used when doing so.

This method is called for scripts defined for the system or station, and is called once for each good in that market. To allow the same script to be applied to multiple systems or stations, the station and system parameters will give the current context.

Here is an example how to use this function.