Trade-goods.plist

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

The trade-goods.plist file replaces and extends the old commodities.plist and illegal_goods.plist files from Oolite 1.81 onwards to allow greater flexibility in trade good definitions, including defining entirely new goods.

The file is a dictionary, with keys as commodity keys, and values defining the quantities, prices and other properties of those commodities.

{
	"food" = {
		"name" = "[commodity-name food]";
		"classes" = ("oolite-consumer","oolite-edible","oolite-farming");
		"quantity_unit" = 0;  // 0=t
		"peak_export" = 7; // Poor Ag
		"peak_import" = 0; // Rich Ind
		"price_average" = 50; // decicredits
		// fraction of average ~= 2.75 credits
		"price_economic" = 0.55;
		// fraction of average ~= 0.2 credits
		"price_random" = 0.04;
		"quantity_average" = 13.5; // gets rounded
		"quantity_economic" = 0.52;
		"quantity_random" = 0.04;
		"legality_export" = 0;
		"legality_import" = 0;
		"trumble_opinion" = 1.0;
		"sort_order" = 100;
	};
}

The following keys are accepted within a commodity definition

Property keys

capacity

The maximum amount of this good which can be held at a main station market. The default is 127 units.

classes

An array of good class names. Good classes can be used by secondary stations to set pricing rules for groups of goods.

The following classes are defined by Oolite, with the core goods in those classes also listed. OXPs should usually add these classes as appropriate to custom trade goods they create, and may also define their own classes (which should be given an OXP-specific prefix). Some built-in classes only contain one built-in good, to allow for easier sub-typing by OXPs.

• oolite-alien: goods which were not made by a Cooperative species (Alien Items)
• oolite-animalproduct: goods which are obtained from animals but are not themselves animals (Furs)
• oolite-business: goods which are usually obtained for industrial or other corporate use (Computers, Machinery, Alloys, Minerals, Gold, Platinum)
• oolite-consumer: goods often obtained for personal use (Food, Textiles, Liquor/Wines, Luxuries, Narcotics, Furs, Gold, Platinum, Gem Stones)
• oolite-dangerous: goods which may be hazardous (Radioactives, Narcotics, Firearms)
• oolite-edible: goods which can be eaten reasonably safely (Food, Liquor/Wines)
• oolite-farming: goods which are produced by farming or similar agricultural processes (Food, Textiles, Liquor/Wines, Furs)
• oolite-living: goods which contain living creatures (Slaves)
• oolite-luxury: goods which are luxuries, usually a subset of oolite-consumer (Luxuries)
• oolite-machinery: goods which are industrial machinery (Machinery)
• oolite-medical: goods which may have a medical purpose (Narcotics)
• oolite-metals: goods which are largely or entirely made of metal (Alloys, Gold, Platinum)
• oolite-military: goods which are of interest to the military (Firearms, Alien Items)
• oolite-mining: goods which are produced by mining operations or similar extraction processes (Radioactives, Minerals, Gold, Platinum, Gem Stones)
• oolite-rawmaterials: goods which are raw materials needing refining to be used further (Minerals)
• oolite-restricted: goods which are subject to restrictions on trade (Slaves, Narcotics, Firearms)
• oolite-salvage: goods which are often retrieved from space battles (Slaves, Alloys)
• oolite-shipyard: goods used in the production of space ships (Computers, Alloys)
• oolite-slaves: goods which are slaves (Slaves)
• oolite-technological: goods requiring a high-tech process to produce (Computers, Machinery)
• oolite-thargoid: goods of Thargoid origin (Alien Items)
• oolite-weapons: goods which are weapons (Firearms)
• oolite-wearable: goods which are or can be used to make clothes (Textiles, Furs)

comment

A string that will be displayed on the F8 F8 commodity detail screen to describe the commodity. This can be modified later by manifest.setComment()

legality_export

This number will be multiplied by the number of units carried when leaving a main station (or another station which enforces Cooperative market laws). This value will be ORed with the player's bounty.

legality_import

This number will be multiplied by the number of units carried when entering a main station (or another station which enforces Cooperative market laws). This value will be ORed with the player's bounty.

No core game good is illegal to import.

market_script

The name of a Javascript file to use as a market script for this trade good when calculating main station quantities and prices.

name

A string containing the name of the trade good. This may contain []s for descriptions.plist expansion.

peak_export

A number from 0 to 7 identifying the economy which will give the best price for buying this good. Economies closer to this economy than the peak_import will also have below-average prices.

peak_import

A number from 0 to 7 identifying the economy which will give the best price for selling this good. Economies closer to this economy than the peak_export will also have above-average prices.

price_average

The average price of this trade good at a main system station which neither imports nor exports, in decicredits.

price_economic

The proportion of the price affected by the system economy. A value of 0 means that this good does not change in price depending on system economy. A value of 0.3 means that the good would be 0.7 times price_average in an ideal exporting system, and 1.3 times price_average in an ideal importing system. While values greater than 1 may be used, in general much lower values are better.

price_random

The proportion of the price affected by random factors. A value of 0.6 means that the actual price of the good in a system which neither imports nor exports may be between 0.4 and 1.6 times the price_average.

If this value is larger than price_economic, this means that even an ideal trade run from the best exporter to the best importer is not guaranteed to make a profit.

quantity_average

The average quantity of this trade good at a main system station which neither imports nor exports, in decicredits. If the calculated quantity exceeds the capacity, it will be capped.

quantity_economic

The proportion of the quantity affected by the system economy. A value of 0 means that this good does not change in quantity depending on system economy. A value of 0.3 means that the good would be 0.7 times as frequent in an ideal importing system, and 1.3 times as frequent in an ideal exporting system. A value of 1 or greater will make the good never or rarely (depending on quantity_random) available in systems which import the good.

quantity_random

The proportion of the quantity affected by random factors. A value of 0.6 means that the actual quantity of the good in a system which neither imports nor exports may be between 0.4 and 1.6 times the quantity_average.

If this value is greater than 1, then systems may often entirely lack this good. If this value is greater than 1 + quantity_economic, then even an ideal exporter may not have any in stock.

quantity_unit

The size of container one unit of this good represents. 0 = tonne; 1 = kilogram; 2 = gram. The default is zero.

short_comment

A string that will be displayed on the F8 commodity list screen in the optional extra column. This can be modified later by manifest.setShortComment(). As the meaning of this value will depend on the OXPs installed, it is unlikely to be useful to specify an initial value in the plist.

sort_order

A number positioning the item on the F8 screen when goods are sorted in the default order. The core goods have values 100 to 1700 in steps of 100.

trumble_opinion

How likely is a hungry trumble to consider eating this good? Goods with a value of 0 for this will never be eaten by trumbles; other goods may be eaten depending on the value of this parameter and the values for other goods on board.

Secondary Market Definitions

Secondary market definitions are entered in the market_definition key in shipdata.plist, which is an array of dictionaries, each defining rules which modify the prices and quantities from the main station market, and possibly adjust the market capacity and legality of the good. The following modifications are applied for each trade good, assuming no market_script is defined:

1. The market definition array is searched from top to bottom for the first element matching the trade good
2. The market quantity is scaled in proportion to the relative capacities for that good in the two markets.
3. Otherwise, the price and quantity modifications defined in the plist are used.

Secondary Market Matching

This uses the 'type' and 'name' properties. Type has three possible values

• type = 'good': the good with the key in trade-goods.plist exactly matching the name property
• type = 'class': any good in trade-goods.plist with an entry in its classes list exactly matching the name property
• type = 'default': any good. The name property is ignored if present.

'default' should generally only be used for the last entry in the market definition.

Secondary Market Modifications

The following keys in the chosen market definition are then used to modify the good

capacity

The market capacity for this good or set of goods. If omitted, the default capacity for the station will be used.

legality_import, legality_export

If present, these keys override the keys of the same name in the basic trade good definition. If omitted, the station will use the same rules as the main station, provided that its market is monitored at all

price_adder, price_multiplier, price_randomiser

These keys modify the price in the secondary market. The formula is (in decicredits):

rnd = -1..1 // random number in range -1 to +1, slightly biased towards zero
secondary_price = MAX(1, (primary_price + price_adder) * (price_multiplier + (price_randomiser * rnd)))

As an exception, if price_adder and price_multiplier are both <= 0, then the result is always 0 regardless of price_random.

quantity_adder, quantity_multiplier, quantity_randomiser

These keys together with the capacity modify the quantity in the secondary market. The formula is:

rnd = -1..1 // random number in range -1 to +1, slightly biased towards zero
adjusted_quantity = (local_capacity / primary_capacity) * primary_quantity;
secondary_quantity = (adjusted_quantity + quantity_adder) * (quantity_multiplier + (quantity_randomiser * rnd)))

As an exception, if quantity_adder and quantity_multiplier are both <= 0, then the result is always 0 regardless of quantity_random.

Examples

Hardly anybody ended up using this! And cim never even put it into his New Cargoes oxp! Spara wrote a conversion script for the old commodities.plist, and everybody seems to have used that instead.

From the core game: Rock Hermits

From the shipdata.plist in the config folder

	"oolite_template_rock-hermit" = 
	{	....
		is_carrier = 1;
		is_template = 1;
		"market_capacity" = 31; // maximum capacity for any good
		"market_definition" = (
			{
				// export cheap mining products
				"type" = "class";
				"name" = "oolite-mining";
				"price_multiplier" = 0.8;
				"price_randomiser" = 0.1;
				"quantity_multiplier" = 3.5;
				"quantity_randomiser" = 3.0;
			},
			{
				// import supplies a bit
				"type" = "class";
				"name" = "oolite-edible";
				"price_multiplier" = 1.05;
				"price_randomiser" = 0.05;
				"quantity_multiplier" = 0.0;
				"capacity" = 15;
			},
			{
				// sometimes need clothes, but usually have enough already
				"type" = "class";
				"name" = "oolite-wearable";
				"price_multiplier" = 0.8;
				"price_randomiser" = 0.4;
				"quantity_multiplier" = 0.0;
				"capacity" = 7;
			},
			{
				// sometimes need new mining equipment
				"type" = "class";
				"name" = "oolite-machinery";
				"price_multiplier" = 0.8;
				"price_randomiser" = 0.4;
				"quantity_multiplier" = 0.0;
				"capacity" = 7;
			},
			{
				// not really interested
				"type" = "default";
				"price_multiplier" = 0.55;
				"price_randomiser" = 0.25;
				"quantity_multiplier" = 0.0;
				"capacity" = 3;
			}
		);
		"market_monitored" = no;
		....
	};

From Cim's oxp: Risk-based Economy (v.2.0, updated from commodities.plist)

{
	"food" = {
		"price_random" = 0.15;
	};
	
	"radioactives" = {
		"price_random" = 0.12;
	};

	"liquor_wines" = {
		"price_random" = 0.15;
	};
	
	"luxuries" = {
		"price_random" = 0.08;
	};

	"luxuries" = {
		"price_random" = 0.08;
	};

	"computers" = {
		"price_random" = 0.12;
	};

	"machinery" = {
		"price_random" = 0.05;
	};

	"alloys" = {
		"price_average" = 158;
		"price_economic" = 0.10;
		"price_random" = 0.06;
	};

	"firearms" = {
		"price_random" = 0.20;
	};

	"furs" = {
		"price_random" = 0.25;
	};

	"alien_items" = {
		"price_economic" = 0.05;
		"price_random" = 0.45;
	};

}

Links

• Oolite JavaScript Reference: Market Scripts
• Commodities.plist - the precursor (which still mostly works!).
• Proposal for 1.82: support for economic changes (Cim, 2014)
• Cim on introducing the Trade-goods.plist and deprecating the commodities.plist (2014)

Trade goods work is coming along fairly well. As well as plist-coded prices for trade goods, which should handle the simple cases (including a few things not possible with commodities.plist), you can now specify a "market script" which allows you to set prices per trade-good, per station, or per system. If you try to do all three, the following happens: 1) The per-trade good script sets a standard price and quantity for the system's economy and any other data it considers 2) The per-system script can then modify this price and quantity 3) The station takes the price and quantity from the system, and scales the quantity to the capacity of the station market 4) The per-trade good script runs again in "secondary station" mode, to modify the price and quantity again 5) The per-station script runs to make final adjustments to price and quantity Generally one OXP wouldn't do all three, though.

(Cim in Progress Thread (2014))

Using the Trade-goods.plist

• How to get the displayName for a commodity in the Main Station Market? (2020)