Elite Wiki - User contributions [en]

Trade-goods (abridged)

2026-06-23T10:56:17Z

Wildeblood: /* What methods might lurk in any damned script? */

'''You are probably looking for [[Trade-goods.plist]]''', rather than this page.

[[File:Distant Riches.png|thumb|right|200px|MORE THAN FIFTY NEW TRADE GOODS]]

== F.A.Q. ==

The goal of this page is to answer the following questions.

=== How many different places can market influences be hiding? ===

In plists, in market scripts, and in station methods in ''any damned script''.

==== Which plists exactly? ====

At least trade-goods.plist , shipdata.plist , shipdata-overrides.plist , planetinfo.plist can set '''market definitions''' directly.

At least trade-goods.plist , shipdata.plist , shipdata-overrides.plist , planetinfo.plist can set links to '''market scripts'''.

==== Which market scripts exactly? ====

See below.

==== What methods might lurk in ''any damned script''? ====

station.setMarketPrice() or
station.setMarketQuantity()

[quote=Switeck post_id=306192 time=1782133939 user_id=3036]
The commodities markets for each add-on station is another issue -- often using fixed scripting instead of borrowing the main station's prices and quantities, or worse...completely broken (0 prices, 0 quantities).
[/quote]

=== How do we define a new "trade-good" (commodity) '''non-bogusly?''' ===

With trade-goods.plist

=== How will sub-standard OXPs thwart us? ===

By careless use of "default" in market influences to destroy things they don't even know exist.

==== Can we move the world-script in AristoShares OXP into a market script? ====

That would prevent deadbeat scripts from interfering with it. Good idea, research required.

=== Can we define new properties for commodities? ===

Where can we set "aita_image" values?

=== Is the economy 0<->7 dipole set in stone? ===

Does it really require javascript to overcome this?

If so, what is the actual function of the peak_import & peak_export properties?

== Preamble ==

The trade-goods.plist file defines "trade goods" (commodities/cargo). But, it does not ''e.g.'' remove slaves from a particular station or make them cost twice as much as they do at the main orbital station. To do such things, ''i.e.'' to tweak the pricing/availability of commodities in a particular station, you need to define the market inside that station, either within its [[Shipdata.plist]] or within a [[Oolite_Market_Scripts|market script]] linked from its shipdata.plist.

== Overview ==

The '''trade-goods.plist''' file is a dictionary of dictionaries, with (canonical) commodity names as keys to dictionaries of key-value pairs 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 (listed thematically, not alphabetically) ==

=== classes ===
An array of commodity class names. Classes can be used by secondary stations (only secondary markets?) to set pricing rules for groups of commodities.

=== market_script ===
The name of a Javascript file to use as a [[Oolite Market Scripts|market script]] for this trade good when calculating main station quantities and prices.

'''Note:''' [https://bb.oolite.space/viewtopic.php?p=235837#p235837 What's the difference between the market script specified in planetinfo.plist and the one called for by trade-goods.plist?] (2015)

=== Display on market screens ===

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

==== comment ====
A string that will be displayed on the F8 F8 commodity detail screen to describe the commodity. This can be modified later by [[Oolite_JavaScript_Reference:_Manifest#setComment|manifest.setComment()]]

==== 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 [[Oolite_JavaScript_Reference:_Manifest#setShortComment|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.

=== Aboard ship ===

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

==== 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.

=== Legality ===

==== 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.

=== Economic biases ===

==== 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.

=== 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.

=== Quantities ===

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

==== 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.''' (Is this true? ''cf.'' Thargoidifier)

==== 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.

=== Discussion of classes ===

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)

== Secondary Market Definitions ==

The primary market is that of the system's main station (''i.e.'' the javascript object system.mainStation.market ) Secondary markets are other markets, which are influenced by the primary market, ''e.g.'' that of a local Rock Hermit, or a visiting liner or another orbital station. Both quantities and prices will be influenced by those of the primary market. Needless to say, the primary market is randomly recalculated each time the system is visited.

Secondary market definitions are entered in the [[shipdata.plist#market_definition|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''':

# The market definition array is searched from top to bottom for the first element matching the trade good
# The market quantity is scaled in proportion to the relative capacities for that good in the two markets.
# 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|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 [[shipdata.plist#market_capacity|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 [[shipdata.plist#market_monitored|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.

=== Links ===
*[https://bb.oolite.space/viewtopic.php?f=2&t=21512 Secondary Market Definitions Defined] (2023)

== 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 for determining markets for new stations.

=== From the vanilla game: Rock Hermits ===
The "market_definition" 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: the Trade-goods.plist updated from the original 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;
};

}
=== A new commodity (from the trade-goods.plist inside "SW Economy") ===
"medicine" = {
"name" = "[commodity-name medicine]";
"classes" = ("oolite-consumer","oolite-medical");
"quantity_unit" = 1;
"peak_export" = 7;
"peak_import" = 0;
"price_average" = 640;
"price_economic" = 0.25;
"price_random" = 0.15;
"quantity_average" = 5;
"quantity_economic" = 1.5;
"quantity_random" = 1.0;
"legality_export" = 0;
"legality_import" = 0;
"trumble_opinion" = 0.50;
"sort_order" = 500;
"comment" = "[oolite-commodity-medicine]";
};

=== Setting an orbital main station's slaves on sale to zero ===
[[User:Phkb|Phkb]] provided this example which requires a ''planetinfo.plist'' & a new ''.js file'' - there are other ways to achieve the same result
==== 1) planetinfo.plist (to invoke the market script) ====
(in the "Config" folder)

{
"0 96" = {market_script = "digebiti_noslaves.js";};
}

==== 2) Market script: digebiti_noslaves.js ====
(in the "Scripts" folder) - note the complex name, which prevents confusion with other snippets of script

"use strict";
this.name = "digebiti_noslaves";
this.author = "Phkb";
this.copyright = "(C) 2022 Phkb";
this.licence = "CC-NC-by-SA 4.0";
this.description = "Removes slaves for sale in Digebiti";
this.version = "1.0";

this.updateLocalCommodityDefinition = function(goodDefinition, station, systemID) {
if (goodDefinition.key == "slaves" && station && station.isMainStation) {
goodDefinition.quantity = 0;
}
return goodDefinition;
}

This method will work, so long as no other OXP changes the market_script property of the Digebiti system in the same way.

=== Creating an invariant market independent of the local system economy (agricultural/industrial) ===
If you just use a market_definition in shipdata.plist for the station, then you're merely setting variations on the primary system market.

If you want the station prices to be independent of (or more loosely tied to) the system it's in, then you need to use a [[Oolite_Market_Scripts|market script]].

So what you'd have is something like this - let's say it's a hydroponics station, so it always sells food and nothing else, regardless of whether the general system economy is industrial or agricultural:

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.key == "food") {
// are we calculating the basic Oolite "food" trade good right now? If yes, set our own static prices
goodDefinition.price = 25; // 2.5 credits
goodDefinition.quantity = 80; // lots of food
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

Now ... the reason that market definitions are preferred to be mutators of the system economy is for two reasons.
1) it means you can avoid the situation where you end up with two adjacent stations with wildly different prices ... but you can of course handle that in other ways too, station positioning, restricted access, ''etc''.
2) it makes it easier to handle OXP trade goods:
- other OXPs might have added more "food" type goods, ''e.g.'' "Meat" or "Cheese"
- you can learn about those and handle them specifically

} else if (goodDefinition.key == "bobsfoodoxp_cheese") {
// set price and quantity here

... but that means a lot of keeping up with what everyone else is doing with custom goods.

The idea was that for your hydroponics station what you might do instead is something like this

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So now if another OXP adds Cheese, provided they declare it as "edible", your station will sell it in high quantities at a big discount, but you don't need to know exactly what the baseline price or quantity was set - so if a food-focused OXP was to add "Wine", "Fine Wine" and "Vintage Wine" at a range of prices and quantities, you'd be automatically handling those in reasonable line with a combination of the Wine OXP's basic pricing structure and your station OXP's "food primary source market" style, without necessarily needing to know about every future Wine OXP there might be and explicitly set compatibility.

Note in this example we're still zeroing out all non-food goods - OXP included! - regardless of the local economy. Maybe at this point we'd want to include and document a "hydroponicsoxp-agriculturalequipment" trade good class that other OXPs could use, which this station would buy up at higher demand and prices than normal.

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else if (goodDefinition.classes.indexOf("hydroponicsoxp-agriculturalequipment") >= 0) {
// custom class for other OXPs to add specific agricultural equipment e.g. combine harvesters, compost, fertiliser
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.capacity = 16; // buy a small amount only // TODO: raise capacity if price per tonne is low
goodDefinition.quantity = 0; // not selling this
} else if (goodDefinition.key == "machinery") {
// the basic Oolite Machinery commodity isn't in the custom class but we need to buy something if
// no OXPs adding it are installed
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.quantity = 0; // not selling
goodDefinition.capacity = 16; // small capacity to buy
} else {
// don't buy or sell any other commodity
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So you can see this one has a mix of using, mutating and overruling the definitions set by the system market and OXP commodity definitions ... with this method you could have a whole bunch of OXPs setting up themed stations, and a whole different bunch adding their own custom commodities, and they'd barely have to know about each other to ensure reasonable consistency and compatibility from someone installing any combination of them. (- by [[User:Cim|Cim]], 2023)

Note: this gives examples for 1 commodity at a time, but not how to easily do that for ALL the commodities on ALL the extra stations in a system.

== Using the trade-goods.plist ==
The trade-goods.plist was designed to make commodities simpler, but only made it more comprehensible. It didn't really let one do anything particularly different to Elite 84 markets - mostly including the "Rich Industrial -> Poor Agricultural" single spectrum. One can tweak that a bit with peak_export and peak_import to get slightly different shapes (so a commodity might peak at Poor Industrial rather than Rich Industrial) but it doesn't really give one the option of a third economy type still.

''So how does one introduce a new economic pole, such as a mining industry?''

For that, one needs the scripting support. [[Oolite JavaScript Reference: Market Scripts]]. 
One can quite literally do whatever one likes with the prices that way. One could have every *system* have its own separate economy, which varied over time according to events, what the player had previously traded, ''etc. etc.'' to produce something comparable to Elite Dangerous' economic sim, if that's the route one wanted to go down. Obviously the more complexity one adds the harder it gets to script up, but it's now all possible.

[[File:SOTL Altmap F8.png|thumb|right|200px|SOTL Altmap F8 commodities market]]
[[SOTL Altmap]] does have an example of it, which basically throws out the original Elite-like algorithm of trade-goods.plist and starts over. It goes *way* beyond just adding a third economy, too.

Basically in SOTL every trade good is tagged in the trade-goods.plist with a bunch of classes
''e.g.''
classes = ("sotl-ex-salvage","sotl-im-refining","sotl-quantity-high","sotl-priceband-3","sotl-demand-medium","sotl-supply-medium","sotl-volatility-low");
So that means:
- exported by salvage economies
- imported by refining economies
- high quantity, moderate price, low price volatility

Then the market script uses those classes, rather than the standard pricing variables, to define the economic behaviour.
:So line 69-74ish: get the current economy description, convert that to the format used in the class name
:...line 85-90: check for the import and export classes for that economy and see if it's imported or exported
:...lines 100-120: apply various special conditions, so e.g. the sotl-ims-radiation class checks the planet surface radiation levels (custom property in sysinfo) and if the radiation level is high, imports these goods even if the basic economy isn't interested (e.g. "sotl-ceramics-ind" in the plist)
:...and then it uses those calculations (and a bunch more of the classes) in the rest of the script to set the price and quantity depending on whether it's an import, an export, or neither

That's massive overkill for just adding a third mining economy, but one would need to work on a similar principle.

:1) Tag every commodity with classes for (import|export|none)-(agricultural|industrial|mining) as appropriate
:2) Adjust the economy names (there are a few different ways one could do that) so that the 8 economy IDs were allocated to agricultural, industrial and mining economies
:3) Have a price script which like the SOTL one gets the current economy, looks at the classes list to find out if the commodity is imported or exported or neither, and sets the price and quantity accordingly. One could use the standard price_economic, price_average, price_random properties in the plist to give baseline data to the script if one was not planning to do anything too weird.

{Technically one doesn't need the classes - just have the price script contain a list of goods internally for each economy - but this way if other people add extra trade goods in their own OXPs, they can tag them up for mining economy support too}

All fairly straightforward theoretically.

''The biggest impediment to doing a wholesale reworking of the economic system, is just how incompatible it makes lots and lots of OXP's. In order to override the vanilla commodities as in SOTL, requires setting a script for each in trade-goods.plist. Which is fine if it's the only OXP that wants to play around with commodity prices. As soon as two OXP's try to do the same thing, one gets a conflict and no longer knows which OXP pricing model is in play.''

''For SOTL it's fine, because it uses the scenario system to forcibly eject all other OXP's from use while it's running. But if one wants the OXP to go in the general playing pool set of OXP's, it becomes much more complicated. [[User:Phkb|Phkb]] spent a long time trying to work out why his market script wasn't running, only to find that [[UPS Courier]] was quietly adjusting the markets in certain systems via the planetinfo.plist file. And there are a lot of OXP's that want to play in this space, tweaking prices up or down.''

''Hence one usually abandons using any of the script options, and just tweaks the price after all the scripts have finished playing, ''eg'' in [[Smugglers]]. It was the only way to guarantee getting some sort of bump in a price when wanted.''

== Links ==
*[[Oolite JavaScript Reference: Market Scripts]]
*[[Commodities.plist]] - the precursor (which still mostly works!). If it doesn't see [https://bb.oolite.space/viewtopic.php?p=246145#p246145 here] (2015)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16828 Proposal for 1.82: support for economic changes] ([[User:Cim|Cim]], 2014)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16735 Cim on introducing the Trade-goods.plist and deprecating the commodities.plist] (2014)
{{QuoteText|Text=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.|Source=([https://bb.oolite.space/viewtopic.php?p=226722#p226722 Cim in Progress Thread (2014)])}}
=== Using the Trade-goods.plist ===
*[https://bb.oolite.space/viewtopic.php?f=4&t=20576 How to get the displayName for a commodity in the Main Station Market?] (2020)
*[https://bb.oolite.space/viewtopic.php?f=6&t=17269 Thinking about Planet Income classification] (2015)

{{QuoteText|Text=
In 1.81 this is a lot easier to OXP - you can introduce as many economies as you like, though you are limited to eight economy symbols (so if you wanted lots of economy types, you might end up with Poor Industrial, Avg Industrial and Rich Industrial sharing a symbol on the map). The trade good pricing scripts can then be used to set up different price categories in different economies (and introduce additional trade goods, or split an existing good into multiple categories, which may be necessary if you're adding more economies).

Resetting economies across the planets is a big change in terms of lines of code, but is also very easy to automate. If OXPers are looking for a scripting tool to use for this sort of automation, then NodeJS or io.js is free and also uses Javascript as its language, so you don't need to learn a new one - and may even be able to share code between your build scripts and your OXP, though I haven't tried that yet.|Source=([https://bb.oolite.space/viewtopic.php?f=6&t=17269 Cim in Planet Income thread (2015)])}}

== Preamble ==
To tweak the pricing/availability of commodities in (''eg''.) a station, you need to define the market inside the station's Shipdata.plist - or include a "hook" inside that shipdata.plist to a javascript Oolite Market Script (which allows more complex definitions).

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:

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

== Handlers ==

=== updateGeneralCommodityDefinition ===
{{oolite-method-added|1.81}}
function updateGeneralCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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 = <code>false</code> 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 ===
{{oolite-method-added|1.81}}
function updateLocalCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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.

[https://bb.oolite.space/viewtopic.php?f=4&t=17621#p239979 Here is an example] of how to use this method.

== Links ==

=== Examples ===
*Phkb's update of [[SW_Economy]] (v.3.10) creates new economies for "mining worlds" (hewn out from some low tech poor agricultural worlds) with utterly different price scales for mineral, agricultural & industrial goods, as well as medicine.

''These others will be found at the bottom of the wiki page on the'' [[Trade-goods.plist]].
*Setting an orbital main station's slaves on sale to zero
*Creating an invariant market independent of the local system economy (agricultural/industrial)

File:AI Trading Backup Datalogger 3.oxz

2026-06-23T10:28:59Z

Wildeblood: /* Summary */

== Summary ==

For clarification of "What does 3-ish mean?":

- The data structure Trading Assistant 3 will use will not change.
- The script inside this OXZ will not change.
- Only the equipment.plist file (to make Trading Assistant harder to acquire)
and the manifest.plist file (to list known incompatibilities) will change.
- This is safe to use.

I plan to publish Trading Assistant 3 sometime during August, 2026.

Trade-goods (abridged)

2026-06-19T15:26:12Z

Wildeblood: /* Using the trade-goods.plist */

'''You are probably looking for [[Trade-goods.plist]]''', rather than this page.

[[File:Distant Riches.png|thumb|right|200px|MORE THAN FIFTY NEW TRADE GOODS]]

== F.A.Q. ==

The goal of this page is to answer the following questions.

=== How many different places can market influences be hiding? ===

In plists, in market scripts, and in station methods in ''any damned script''.

==== Which plists exactly? ====

At least trade-goods.plist , shipdata.plist , shipdata-overrides.plist , planetinfo.plist can set '''market definitions''' directly.

At least trade-goods.plist , shipdata.plist , shipdata-overrides.plist , planetinfo.plist can set links to '''market scripts'''.

==== Which market scripts exactly? ====

See below.

==== What methods might lurk in ''any damned script''? ====

station.setMarketPrice() or
station.setMarketQuantity()

=== How do we define a new "trade-good" (commodity) '''non-bogusly?''' ===

With trade-goods.plist

=== How will sub-standard OXPs thwart us? ===

By careless use of "default" in market influences to destroy things they don't even know exist.

==== Can we move the world-script in AristoShares OXP into a market script? ====

That would prevent deadbeat scripts from interfering with it. Good idea, research required.

=== Can we define new properties for commodities? ===

Where can we set "aita_image" values?

=== Is the economy 0<->7 dipole set in stone? ===

Does it really require javascript to overcome this?

If so, what is the actual function of the peak_import & peak_export properties?

== Preamble ==

The trade-goods.plist file defines "trade goods" (commodities/cargo). But, it does not ''e.g.'' remove slaves from a particular station or make them cost twice as much as they do at the main orbital station. To do such things, ''i.e.'' to tweak the pricing/availability of commodities in a particular station, you need to define the market inside that station, either within its [[Shipdata.plist]] or within a [[Oolite_Market_Scripts|market script]] linked from its shipdata.plist.

== Overview ==

The '''trade-goods.plist''' file is a dictionary of dictionaries, with (canonical) commodity names as keys to dictionaries of key-value pairs 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 (listed thematically, not alphabetically) ==

=== classes ===
An array of commodity class names. Classes can be used by secondary stations (only secondary markets?) to set pricing rules for groups of commodities.

=== market_script ===
The name of a Javascript file to use as a [[Oolite Market Scripts|market script]] for this trade good when calculating main station quantities and prices.

'''Note:''' [https://bb.oolite.space/viewtopic.php?p=235837#p235837 What's the difference between the market script specified in planetinfo.plist and the one called for by trade-goods.plist?] (2015)

=== Display on market screens ===

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

==== comment ====
A string that will be displayed on the F8 F8 commodity detail screen to describe the commodity. This can be modified later by [[Oolite_JavaScript_Reference:_Manifest#setComment|manifest.setComment()]]

==== 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 [[Oolite_JavaScript_Reference:_Manifest#setShortComment|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.

=== Aboard ship ===

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

==== 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.

=== Legality ===

==== 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.

=== Economic biases ===

==== 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.

=== 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.

=== Quantities ===

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

==== 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.''' (Is this true? ''cf.'' Thargoidifier)

==== 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.

=== Discussion of classes ===

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)

== Secondary Market Definitions ==

The primary market is that of the system's main station (''i.e.'' the javascript object system.mainStation.market ) Secondary markets are other markets, which are influenced by the primary market, ''e.g.'' that of a local Rock Hermit, or a visiting liner or another orbital station. Both quantities and prices will be influenced by those of the primary market. Needless to say, the primary market is randomly recalculated each time the system is visited.

Secondary market definitions are entered in the [[shipdata.plist#market_definition|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''':

# The market definition array is searched from top to bottom for the first element matching the trade good
# The market quantity is scaled in proportion to the relative capacities for that good in the two markets.
# 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|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 [[shipdata.plist#market_capacity|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 [[shipdata.plist#market_monitored|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.

=== Links ===
*[https://bb.oolite.space/viewtopic.php?f=2&t=21512 Secondary Market Definitions Defined] (2023)

== 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 for determining markets for new stations.

=== From the vanilla game: Rock Hermits ===
The "market_definition" 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: the Trade-goods.plist updated from the original 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;
};

}
=== A new commodity (from the trade-goods.plist inside "SW Economy") ===
"medicine" = {
"name" = "[commodity-name medicine]";
"classes" = ("oolite-consumer","oolite-medical");
"quantity_unit" = 1;
"peak_export" = 7;
"peak_import" = 0;
"price_average" = 640;
"price_economic" = 0.25;
"price_random" = 0.15;
"quantity_average" = 5;
"quantity_economic" = 1.5;
"quantity_random" = 1.0;
"legality_export" = 0;
"legality_import" = 0;
"trumble_opinion" = 0.50;
"sort_order" = 500;
"comment" = "[oolite-commodity-medicine]";
};

=== Setting an orbital main station's slaves on sale to zero ===
[[User:Phkb|Phkb]] provided this example which requires a ''planetinfo.plist'' & a new ''.js file'' - there are other ways to achieve the same result
==== 1) planetinfo.plist (to invoke the market script) ====
(in the "Config" folder)

{
"0 96" = {market_script = "digebiti_noslaves.js";};
}

==== 2) Market script: digebiti_noslaves.js ====
(in the "Scripts" folder) - note the complex name, which prevents confusion with other snippets of script

"use strict";
this.name = "digebiti_noslaves";
this.author = "Phkb";
this.copyright = "(C) 2022 Phkb";
this.licence = "CC-NC-by-SA 4.0";
this.description = "Removes slaves for sale in Digebiti";
this.version = "1.0";

this.updateLocalCommodityDefinition = function(goodDefinition, station, systemID) {
if (goodDefinition.key == "slaves" && station && station.isMainStation) {
goodDefinition.quantity = 0;
}
return goodDefinition;
}

This method will work, so long as no other OXP changes the market_script property of the Digebiti system in the same way.

=== Creating an invariant market independent of the local system economy (agricultural/industrial) ===
If you just use a market_definition in shipdata.plist for the station, then you're merely setting variations on the primary system market.

If you want the station prices to be independent of (or more loosely tied to) the system it's in, then you need to use a [[Oolite_Market_Scripts|market script]].

So what you'd have is something like this - let's say it's a hydroponics station, so it always sells food and nothing else, regardless of whether the general system economy is industrial or agricultural:

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.key == "food") {
// are we calculating the basic Oolite "food" trade good right now? If yes, set our own static prices
goodDefinition.price = 25; // 2.5 credits
goodDefinition.quantity = 80; // lots of food
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

Now ... the reason that market definitions are preferred to be mutators of the system economy is for two reasons.
1) it means you can avoid the situation where you end up with two adjacent stations with wildly different prices ... but you can of course handle that in other ways too, station positioning, restricted access, ''etc''.
2) it makes it easier to handle OXP trade goods:
- other OXPs might have added more "food" type goods, ''e.g.'' "Meat" or "Cheese"
- you can learn about those and handle them specifically

} else if (goodDefinition.key == "bobsfoodoxp_cheese") {
// set price and quantity here

... but that means a lot of keeping up with what everyone else is doing with custom goods.

The idea was that for your hydroponics station what you might do instead is something like this

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So now if another OXP adds Cheese, provided they declare it as "edible", your station will sell it in high quantities at a big discount, but you don't need to know exactly what the baseline price or quantity was set - so if a food-focused OXP was to add "Wine", "Fine Wine" and "Vintage Wine" at a range of prices and quantities, you'd be automatically handling those in reasonable line with a combination of the Wine OXP's basic pricing structure and your station OXP's "food primary source market" style, without necessarily needing to know about every future Wine OXP there might be and explicitly set compatibility.

Note in this example we're still zeroing out all non-food goods - OXP included! - regardless of the local economy. Maybe at this point we'd want to include and document a "hydroponicsoxp-agriculturalequipment" trade good class that other OXPs could use, which this station would buy up at higher demand and prices than normal.

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else if (goodDefinition.classes.indexOf("hydroponicsoxp-agriculturalequipment") >= 0) {
// custom class for other OXPs to add specific agricultural equipment e.g. combine harvesters, compost, fertiliser
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.capacity = 16; // buy a small amount only // TODO: raise capacity if price per tonne is low
goodDefinition.quantity = 0; // not selling this
} else if (goodDefinition.key == "machinery") {
// the basic Oolite Machinery commodity isn't in the custom class but we need to buy something if
// no OXPs adding it are installed
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.quantity = 0; // not selling
goodDefinition.capacity = 16; // small capacity to buy
} else {
// don't buy or sell any other commodity
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So you can see this one has a mix of using, mutating and overruling the definitions set by the system market and OXP commodity definitions ... with this method you could have a whole bunch of OXPs setting up themed stations, and a whole different bunch adding their own custom commodities, and they'd barely have to know about each other to ensure reasonable consistency and compatibility from someone installing any combination of them. (- by [[User:Cim|Cim]], 2023)

Note: this gives examples for 1 commodity at a time, but not how to easily do that for ALL the commodities on ALL the extra stations in a system.

== Using the trade-goods.plist ==
The trade-goods.plist was designed to make commodities simpler, but only made it more comprehensible. It didn't really let one do anything particularly different to Elite 84 markets - mostly including the "Rich Industrial -> Poor Agricultural" single spectrum. One can tweak that a bit with peak_export and peak_import to get slightly different shapes (so a commodity might peak at Poor Industrial rather than Rich Industrial) but it doesn't really give one the option of a third economy type still.

''So how does one introduce a new economic pole, such as a mining industry?''

For that, one needs the scripting support. [[Oolite JavaScript Reference: Market Scripts]]. 
One can quite literally do whatever one likes with the prices that way. One could have every *system* have its own separate economy, which varied over time according to events, what the player had previously traded, ''etc. etc.'' to produce something comparable to Elite Dangerous' economic sim, if that's the route one wanted to go down. Obviously the more complexity one adds the harder it gets to script up, but it's now all possible.

[[File:SOTL Altmap F8.png|thumb|right|200px|SOTL Altmap F8 commodities market]]
[[SOTL Altmap]] does have an example of it, which basically throws out the original Elite-like algorithm of trade-goods.plist and starts over. It goes *way* beyond just adding a third economy, too.

Basically in SOTL every trade good is tagged in the trade-goods.plist with a bunch of classes
''e.g.''
classes = ("sotl-ex-salvage","sotl-im-refining","sotl-quantity-high","sotl-priceband-3","sotl-demand-medium","sotl-supply-medium","sotl-volatility-low");
So that means:
- exported by salvage economies
- imported by refining economies
- high quantity, moderate price, low price volatility

Then the market script uses those classes, rather than the standard pricing variables, to define the economic behaviour.
:So line 69-74ish: get the current economy description, convert that to the format used in the class name
:...line 85-90: check for the import and export classes for that economy and see if it's imported or exported
:...lines 100-120: apply various special conditions, so e.g. the sotl-ims-radiation class checks the planet surface radiation levels (custom property in sysinfo) and if the radiation level is high, imports these goods even if the basic economy isn't interested (e.g. "sotl-ceramics-ind" in the plist)
:...and then it uses those calculations (and a bunch more of the classes) in the rest of the script to set the price and quantity depending on whether it's an import, an export, or neither

That's massive overkill for just adding a third mining economy, but one would need to work on a similar principle.

:1) Tag every commodity with classes for (import|export|none)-(agricultural|industrial|mining) as appropriate
:2) Adjust the economy names (there are a few different ways one could do that) so that the 8 economy IDs were allocated to agricultural, industrial and mining economies
:3) Have a price script which like the SOTL one gets the current economy, looks at the classes list to find out if the commodity is imported or exported or neither, and sets the price and quantity accordingly. One could use the standard price_economic, price_average, price_random properties in the plist to give baseline data to the script if one was not planning to do anything too weird.

{Technically one doesn't need the classes - just have the price script contain a list of goods internally for each economy - but this way if other people add extra trade goods in their own OXPs, they can tag them up for mining economy support too}

All fairly straightforward theoretically.

''The biggest impediment to doing a wholesale reworking of the economic system, is just how incompatible it makes lots and lots of OXP's. In order to override the vanilla commodities as in SOTL, requires setting a script for each in trade-goods.plist. Which is fine if it's the only OXP that wants to play around with commodity prices. As soon as two OXP's try to do the same thing, one gets a conflict and no longer knows which OXP pricing model is in play.''

''For SOTL it's fine, because it uses the scenario system to forcibly eject all other OXP's from use while it's running. But if one wants the OXP to go in the general playing pool set of OXP's, it becomes much more complicated. [[User:Phkb|Phkb]] spent a long time trying to work out why his market script wasn't running, only to find that [[UPS Courier]] was quietly adjusting the markets in certain systems via the planetinfo.plist file. And there are a lot of OXP's that want to play in this space, tweaking prices up or down.''

''Hence one usually abandons using any of the script options, and just tweaks the price after all the scripts have finished playing, ''eg'' in [[Smugglers]]. It was the only way to guarantee getting some sort of bump in a price when wanted.''

== Links ==
*[[Oolite JavaScript Reference: Market Scripts]]
*[[Commodities.plist]] - the precursor (which still mostly works!). If it doesn't see [https://bb.oolite.space/viewtopic.php?p=246145#p246145 here] (2015)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16828 Proposal for 1.82: support for economic changes] ([[User:Cim|Cim]], 2014)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16735 Cim on introducing the Trade-goods.plist and deprecating the commodities.plist] (2014)
{{QuoteText|Text=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.|Source=([https://bb.oolite.space/viewtopic.php?p=226722#p226722 Cim in Progress Thread (2014)])}}
=== Using the Trade-goods.plist ===
*[https://bb.oolite.space/viewtopic.php?f=4&t=20576 How to get the displayName for a commodity in the Main Station Market?] (2020)
*[https://bb.oolite.space/viewtopic.php?f=6&t=17269 Thinking about Planet Income classification] (2015)

{{QuoteText|Text=
In 1.81 this is a lot easier to OXP - you can introduce as many economies as you like, though you are limited to eight economy symbols (so if you wanted lots of economy types, you might end up with Poor Industrial, Avg Industrial and Rich Industrial sharing a symbol on the map). The trade good pricing scripts can then be used to set up different price categories in different economies (and introduce additional trade goods, or split an existing good into multiple categories, which may be necessary if you're adding more economies).

Resetting economies across the planets is a big change in terms of lines of code, but is also very easy to automate. If OXPers are looking for a scripting tool to use for this sort of automation, then NodeJS or io.js is free and also uses Javascript as its language, so you don't need to learn a new one - and may even be able to share code between your build scripts and your OXP, though I haven't tried that yet.|Source=([https://bb.oolite.space/viewtopic.php?f=6&t=17269 Cim in Planet Income thread (2015)])}}

== Preamble ==
To tweak the pricing/availability of commodities in (''eg''.) a station, you need to define the market inside the station's Shipdata.plist - or include a "hook" inside that shipdata.plist to a javascript Oolite Market Script (which allows more complex definitions).

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:

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

== Handlers ==

=== updateGeneralCommodityDefinition ===
{{oolite-method-added|1.81}}
function updateGeneralCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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 = <code>false</code> 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 ===
{{oolite-method-added|1.81}}
function updateLocalCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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.

[https://bb.oolite.space/viewtopic.php?f=4&t=17621#p239979 Here is an example] of how to use this method.

== Links ==

=== Examples ===
*Phkb's update of [[SW_Economy]] (v.3.10) creates new economies for "mining worlds" (hewn out from some low tech poor agricultural worlds) with utterly different price scales for mineral, agricultural & industrial goods, as well as medicine.

''These others will be found at the bottom of the wiki page on the'' [[Trade-goods.plist]].
*Setting an orbital main station's slaves on sale to zero
*Creating an invariant market independent of the local system economy (agricultural/industrial)

Trade-goods (abridged)

2026-06-19T15:07:57Z

Wildeblood: /* Display on market screens */

'''You are probably looking for [[Trade-goods.plist]]''', rather than this page.

[[File:Distant Riches.png|thumb|right|200px|MORE THAN FIFTY NEW TRADE GOODS]]

== F.A.Q. ==

The goal of this page is to answer the following questions.

=== How many different places can market influences be hiding? ===

In plists, in market scripts, and in station methods in ''any damned script''.

==== Which plists exactly? ====

At least trade-goods.plist , shipdata.plist , shipdata-overrides.plist , planetinfo.plist can set '''market definitions''' directly.

At least trade-goods.plist , shipdata.plist , shipdata-overrides.plist , planetinfo.plist can set links to '''market scripts'''.

==== Which market scripts exactly? ====

See below.

==== What methods might lurk in ''any damned script''? ====

station.setMarketPrice() or
station.setMarketQuantity()

=== How do we define a new "trade-good" (commodity) '''non-bogusly?''' ===

With trade-goods.plist

=== How will sub-standard OXPs thwart us? ===

By careless use of "default" in market influences to destroy things they don't even know exist.

==== Can we move the world-script in AristoShares OXP into a market script? ====

That would prevent deadbeat scripts from interfering with it. Good idea, research required.

=== Can we define new properties for commodities? ===

Where can we set "aita_image" values?

=== Is the economy 0<->7 dipole set in stone? ===

Does it really require javascript to overcome this?

If so, what is the actual function of the peak_import & peak_export properties?

== Preamble ==

The trade-goods.plist file defines "trade goods" (commodities/cargo). But, it does not ''e.g.'' remove slaves from a particular station or make them cost twice as much as they do at the main orbital station. To do such things, ''i.e.'' to tweak the pricing/availability of commodities in a particular station, you need to define the market inside that station, either within its [[Shipdata.plist]] or within a [[Oolite_Market_Scripts|market script]] linked from its shipdata.plist.

== Overview ==

The '''trade-goods.plist''' file is a dictionary of dictionaries, with (canonical) commodity names as keys to dictionaries of key-value pairs 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 (listed thematically, not alphabetically) ==

=== classes ===
An array of commodity class names. Classes can be used by secondary stations (only secondary markets?) to set pricing rules for groups of commodities.

=== market_script ===
The name of a Javascript file to use as a [[Oolite Market Scripts|market script]] for this trade good when calculating main station quantities and prices.

'''Note:''' [https://bb.oolite.space/viewtopic.php?p=235837#p235837 What's the difference between the market script specified in planetinfo.plist and the one called for by trade-goods.plist?] (2015)

=== Display on market screens ===

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

==== comment ====
A string that will be displayed on the F8 F8 commodity detail screen to describe the commodity. This can be modified later by [[Oolite_JavaScript_Reference:_Manifest#setComment|manifest.setComment()]]

==== 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 [[Oolite_JavaScript_Reference:_Manifest#setShortComment|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.

=== Aboard ship ===

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

==== 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.

=== Legality ===

==== 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.

=== Economic biases ===

==== 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.

=== 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.

=== Quantities ===

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

==== 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.''' (Is this true? ''cf.'' Thargoidifier)

==== 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.

=== Discussion of classes ===

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)

== Secondary Market Definitions ==

The primary market is that of the system's main station (''i.e.'' the javascript object system.mainStation.market ) Secondary markets are other markets, which are influenced by the primary market, ''e.g.'' that of a local Rock Hermit, or a visiting liner or another orbital station. Both quantities and prices will be influenced by those of the primary market. Needless to say, the primary market is randomly recalculated each time the system is visited.

Secondary market definitions are entered in the [[shipdata.plist#market_definition|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''':

# The market definition array is searched from top to bottom for the first element matching the trade good
# The market quantity is scaled in proportion to the relative capacities for that good in the two markets.
# 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|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 [[shipdata.plist#market_capacity|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 [[shipdata.plist#market_monitored|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.

=== Links ===
*[https://bb.oolite.space/viewtopic.php?f=2&t=21512 Secondary Market Definitions Defined] (2023)

== 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 for determining markets for new stations.

=== From the vanilla game: Rock Hermits ===
The "market_definition" 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: the Trade-goods.plist updated from the original 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;
};

}
=== A new commodity (from the trade-goods.plist inside "SW Economy") ===
"medicine" = {
"name" = "[commodity-name medicine]";
"classes" = ("oolite-consumer","oolite-medical");
"quantity_unit" = 1;
"peak_export" = 7;
"peak_import" = 0;
"price_average" = 640;
"price_economic" = 0.25;
"price_random" = 0.15;
"quantity_average" = 5;
"quantity_economic" = 1.5;
"quantity_random" = 1.0;
"legality_export" = 0;
"legality_import" = 0;
"trumble_opinion" = 0.50;
"sort_order" = 500;
"comment" = "[oolite-commodity-medicine]";
};

=== Setting an orbital main station's slaves on sale to zero ===
[[User:Phkb|Phkb]] provided this example which requires a ''planetinfo.plist'' & a new ''.js file'' - there are other ways to achieve the same result
==== 1) planetinfo.plist (to invoke the market script) ====
(in the "Config" folder)

{
"0 96" = {market_script = "digebiti_noslaves.js";};
}

==== 2) Market script: digebiti_noslaves.js ====
(in the "Scripts" folder) - note the complex name, which prevents confusion with other snippets of script

"use strict";
this.name = "digebiti_noslaves";
this.author = "Phkb";
this.copyright = "(C) 2022 Phkb";
this.licence = "CC-NC-by-SA 4.0";
this.description = "Removes slaves for sale in Digebiti";
this.version = "1.0";

this.updateLocalCommodityDefinition = function(goodDefinition, station, systemID) {
if (goodDefinition.key == "slaves" && station && station.isMainStation) {
goodDefinition.quantity = 0;
}
return goodDefinition;
}

This method will work, so long as no other OXP changes the market_script property of the Digebiti system in the same way.

=== Creating an invariant market independent of the local system economy (agricultural/industrial) ===
If you just use a market_definition in shipdata.plist for the station, then you're merely setting variations on the primary system market.

If you want the station prices to be independent of (or more loosely tied to) the system it's in, then you need to use a [[Oolite_Market_Scripts|market script]].

So what you'd have is something like this - let's say it's a hydroponics station, so it always sells food and nothing else, regardless of whether the general system economy is industrial or agricultural:

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.key == "food") {
// are we calculating the basic Oolite "food" trade good right now? If yes, set our own static prices
goodDefinition.price = 25; // 2.5 credits
goodDefinition.quantity = 80; // lots of food
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

Now ... the reason that market definitions are preferred to be mutators of the system economy is for two reasons.
1) it means you can avoid the situation where you end up with two adjacent stations with wildly different prices ... but you can of course handle that in other ways too, station positioning, restricted access, ''etc''.
2) it makes it easier to handle OXP trade goods:
- other OXPs might have added more "food" type goods, ''e.g.'' "Meat" or "Cheese"
- you can learn about those and handle them specifically

} else if (goodDefinition.key == "bobsfoodoxp_cheese") {
// set price and quantity here

... but that means a lot of keeping up with what everyone else is doing with custom goods.

The idea was that for your hydroponics station what you might do instead is something like this

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So now if another OXP adds Cheese, provided they declare it as "edible", your station will sell it in high quantities at a big discount, but you don't need to know exactly what the baseline price or quantity was set - so if a food-focused OXP was to add "Wine", "Fine Wine" and "Vintage Wine" at a range of prices and quantities, you'd be automatically handling those in reasonable line with a combination of the Wine OXP's basic pricing structure and your station OXP's "food primary source market" style, without necessarily needing to know about every future Wine OXP there might be and explicitly set compatibility.

Note in this example we're still zeroing out all non-food goods - OXP included! - regardless of the local economy. Maybe at this point we'd want to include and document a "hydroponicsoxp-agriculturalequipment" trade good class that other OXPs could use, which this station would buy up at higher demand and prices than normal.

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else if (goodDefinition.classes.indexOf("hydroponicsoxp-agriculturalequipment") >= 0) {
// custom class for other OXPs to add specific agricultural equipment e.g. combine harvesters, compost, fertiliser
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.capacity = 16; // buy a small amount only // TODO: raise capacity if price per tonne is low
goodDefinition.quantity = 0; // not selling this
} else if (goodDefinition.key == "machinery") {
// the basic Oolite Machinery commodity isn't in the custom class but we need to buy something if
// no OXPs adding it are installed
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.quantity = 0; // not selling
goodDefinition.capacity = 16; // small capacity to buy
} else {
// don't buy or sell any other commodity
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So you can see this one has a mix of using, mutating and overruling the definitions set by the system market and OXP commodity definitions ... with this method you could have a whole bunch of OXPs setting up themed stations, and a whole different bunch adding their own custom commodities, and they'd barely have to know about each other to ensure reasonable consistency and compatibility from someone installing any combination of them. (- by [[User:Cim|Cim]], 2023)

Note: this gives examples for 1 commodity at a time, but not how to easily do that for ALL the commodities on ALL the extra stations in a system.

== Using the trade-goods.plist ==
The trade-goods.plist was designed to make commodities simpler, by:
:1) Making it a dictionary rather than an unlabelled array so one could tell which parameter was which
:2) Making the price range for a trade good dependent on more sensible variables, so rather than setting the price range with a bitmask, one set the price and quantity variations dependent on the economy and on random chance.

Compare the v.1.81 trade-goods.plist with a v.1.80 commodities.plist - they were designed to give near-identical market behaviour for the built-in trade goods.

But - that only made it more comprehensible. It didn't really let one do anything particularly different to Elite 84 markets - mostly including the "Rich Industrial -> Poor Agricultural" single spectrum. One can tweak that a bit with peak_export and peak_import to get slightly different shapes (so a good might peak at Poor Industrial rather than Rich Industrial) but it doesn't really give one the option of a third economy type still.

''So how does one introduce a new economic pole, such as a mining industry?''

For that, one needs the scripting support. [[Oolite JavaScript Reference: Market Scripts]]. 
One can quite literally do whatever one likes with the prices that way. One could have every *system* have its own separate economy, which varied over time according to events, what the player had previously traded, ''etc. etc.'' to produce something comparable to Elite Dangerous' economic sim, if that's the route one wanted to go down. Obviously the more complexity one adds the harder it gets to script up, but it's now all possible.

[[File:SOTL Altmap F8.png|thumb|right|200px|SOTL Altmap F8 commodities market]]
[[SOTL Altmap]] does have an example of it, which basically throws out the original Elite-like algorithm of trade-goods.plist and starts over. It goes *way* beyond just adding a third economy, too.

Basically in SOTL every trade good is tagged in the trade-goods.plist with a bunch of classes
''e.g.''
classes = ("sotl-ex-salvage","sotl-im-refining","sotl-quantity-high","sotl-priceband-3","sotl-demand-medium","sotl-supply-medium","sotl-volatility-low");
So that means:
- exported by salvage economies
- imported by refining economies
- high quantity, moderate price, low price volatility

Then the market script uses those classes, rather than the standard pricing variables, to define the economic behaviour.
:So line 69-74ish: get the current economy description, convert that to the format used in the class name
:...line 85-90: check for the import and export classes for that economy and see if it's imported or exported
:...lines 100-120: apply various special conditions, so e.g. the sotl-ims-radiation class checks the planet surface radiation levels (custom property in sysinfo) and if the radiation level is high, imports these goods even if the basic economy isn't interested (e.g. "sotl-ceramics-ind" in the plist)
:...and then it uses those calculations (and a bunch more of the classes) in the rest of the script to set the price and quantity depending on whether it's an import, an export, or neither

That's massive overkill for just adding a third mining economy, but one would need to work on a similar principle.

:1) Tag every commodity with classes for (import|export|none)-(agricultural|industrial|mining) as appropriate
:2) Adjust the economy names (there are a few different ways one could do that) so that the 8 economy IDs were allocated to agricultural, industrial and mining economies
:3) Have a price script which like the SOTL one gets the current economy, looks at the classes list to find out if the commodity is imported or exported or neither, and sets the price and quantity accordingly. One could use the standard price_economic, price_average, price_random properties in the plist to give baseline data to the script if one was not planning to do anything too weird.

{Technically one doesn't need the classes - just have the price script contain a list of goods internally for each economy - but this way if other people add extra trade goods in their own OXPs, they can tag them up for mining economy support too}

All fairly straightforward theoretically.

''The biggest impediment to doing a wholesale reworking of the economic system, is just how incompatible it makes lots and lots of OXP's. In order to override the vanilla commodities as in SOTL, requires setting a script for each in trade-goods.plist. Which is fine if it's the only OXP that wants to play around with commodity prices. As soon as two OXP's try to do the same thing, one gets a conflict and no longer knows which OXP pricing model is in play.''

''For SOTL it's fine, because it uses the scenario system to forcibly eject all other OXP's from use while it's running. But if one wants the OXP to go in the general playing pool set of OXP's, it becomes much more complicated. [[User:Phkb|Phkb]] spent a long time trying to work out why his market script wasn't running, only to find that [[UPS Courier]] was quietly adjusting the markets in certain systems via the planetinfo.plist file. And there are a lot of OXP's that want to play in this space, tweaking prices up or down.''

''Hence one usually abandons using any of the script options, and just tweaks the price after all the scripts have finished playing, ''eg'' in [[Smugglers]]. It was the only way to guarantee getting some sort of bump in a price when wanted.''

== Links ==
*[[Oolite JavaScript Reference: Market Scripts]]
*[[Commodities.plist]] - the precursor (which still mostly works!). If it doesn't see [https://bb.oolite.space/viewtopic.php?p=246145#p246145 here] (2015)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16828 Proposal for 1.82: support for economic changes] ([[User:Cim|Cim]], 2014)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16735 Cim on introducing the Trade-goods.plist and deprecating the commodities.plist] (2014)
{{QuoteText|Text=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.|Source=([https://bb.oolite.space/viewtopic.php?p=226722#p226722 Cim in Progress Thread (2014)])}}
=== Using the Trade-goods.plist ===
*[https://bb.oolite.space/viewtopic.php?f=4&t=20576 How to get the displayName for a commodity in the Main Station Market?] (2020)
*[https://bb.oolite.space/viewtopic.php?f=6&t=17269 Thinking about Planet Income classification] (2015)

{{QuoteText|Text=
In 1.81 this is a lot easier to OXP - you can introduce as many economies as you like, though you are limited to eight economy symbols (so if you wanted lots of economy types, you might end up with Poor Industrial, Avg Industrial and Rich Industrial sharing a symbol on the map). The trade good pricing scripts can then be used to set up different price categories in different economies (and introduce additional trade goods, or split an existing good into multiple categories, which may be necessary if you're adding more economies).

Resetting economies across the planets is a big change in terms of lines of code, but is also very easy to automate. If OXPers are looking for a scripting tool to use for this sort of automation, then NodeJS or io.js is free and also uses Javascript as its language, so you don't need to learn a new one - and may even be able to share code between your build scripts and your OXP, though I haven't tried that yet.|Source=([https://bb.oolite.space/viewtopic.php?f=6&t=17269 Cim in Planet Income thread (2015)])}}

== Preamble ==
To tweak the pricing/availability of commodities in (''eg''.) a station, you need to define the market inside the station's Shipdata.plist - or include a "hook" inside that shipdata.plist to a javascript Oolite Market Script (which allows more complex definitions).

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:

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

== Handlers ==

=== updateGeneralCommodityDefinition ===
{{oolite-method-added|1.81}}
function updateGeneralCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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 = <code>false</code> 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 ===
{{oolite-method-added|1.81}}
function updateLocalCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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.

[https://bb.oolite.space/viewtopic.php?f=4&t=17621#p239979 Here is an example] of how to use this method.

== Links ==

=== Examples ===
*Phkb's update of [[SW_Economy]] (v.3.10) creates new economies for "mining worlds" (hewn out from some low tech poor agricultural worlds) with utterly different price scales for mineral, agricultural & industrial goods, as well as medicine.

''These others will be found at the bottom of the wiki page on the'' [[Trade-goods.plist]].
*Setting an orbital main station's slaves on sale to zero
*Creating an invariant market independent of the local system economy (agricultural/industrial)

Trade-goods (abridged)

2026-06-19T15:06:40Z

Wildeblood: /* trumble_opinion */

'''You are probably looking for [[Trade-goods.plist]]''', rather than this page.

[[File:Distant Riches.png|thumb|right|200px|MORE THAN FIFTY NEW TRADE GOODS]]

== F.A.Q. ==

The goal of this page is to answer the following questions.

=== How many different places can market influences be hiding? ===

In plists, in market scripts, and in station methods in ''any damned script''.

==== Which plists exactly? ====

At least trade-goods.plist , shipdata.plist , shipdata-overrides.plist , planetinfo.plist can set '''market definitions''' directly.

At least trade-goods.plist , shipdata.plist , shipdata-overrides.plist , planetinfo.plist can set links to '''market scripts'''.

==== Which market scripts exactly? ====

See below.

==== What methods might lurk in ''any damned script''? ====

station.setMarketPrice() or
station.setMarketQuantity()

=== How do we define a new "trade-good" (commodity) '''non-bogusly?''' ===

With trade-goods.plist

=== How will sub-standard OXPs thwart us? ===

By careless use of "default" in market influences to destroy things they don't even know exist.

==== Can we move the world-script in AristoShares OXP into a market script? ====

That would prevent deadbeat scripts from interfering with it. Good idea, research required.

=== Can we define new properties for commodities? ===

Where can we set "aita_image" values?

=== Is the economy 0<->7 dipole set in stone? ===

Does it really require javascript to overcome this?

If so, what is the actual function of the peak_import & peak_export properties?

== Preamble ==

The trade-goods.plist file defines "trade goods" (commodities/cargo). But, it does not ''e.g.'' remove slaves from a particular station or make them cost twice as much as they do at the main orbital station. To do such things, ''i.e.'' to tweak the pricing/availability of commodities in a particular station, you need to define the market inside that station, either within its [[Shipdata.plist]] or within a [[Oolite_Market_Scripts|market script]] linked from its shipdata.plist.

== Overview ==

The '''trade-goods.plist''' file is a dictionary of dictionaries, with (canonical) commodity names as keys to dictionaries of key-value pairs 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 (listed thematically, not alphabetically) ==

=== classes ===
An array of commodity class names. Classes can be used by secondary stations (only secondary markets?) to set pricing rules for groups of commodities.

=== market_script ===
The name of a Javascript file to use as a [[Oolite Market Scripts|market script]] for this trade good when calculating main station quantities and prices.

'''Note:''' [https://bb.oolite.space/viewtopic.php?p=235837#p235837 What's the difference between the market script specified in planetinfo.plist and the one called for by trade-goods.plist?] (2015)

=== Display on market screens ===

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

==== comment ====
A string that will be displayed on the F8 F8 commodity detail screen to describe the commodity. This can be modified later by [[Oolite_JavaScript_Reference:_Manifest#setComment|manifest.setComment()]]

==== 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 [[Oolite_JavaScript_Reference:_Manifest#setShortComment|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.

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

==== 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.

=== Legality ===

==== 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.

=== Economic biases ===

==== 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.

=== 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.

=== Quantities ===

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

==== 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.''' (Is this true? ''cf.'' Thargoidifier)

==== 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.

=== Discussion of classes ===

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)

== Secondary Market Definitions ==

The primary market is that of the system's main station (''i.e.'' the javascript object system.mainStation.market ) Secondary markets are other markets, which are influenced by the primary market, ''e.g.'' that of a local Rock Hermit, or a visiting liner or another orbital station. Both quantities and prices will be influenced by those of the primary market. Needless to say, the primary market is randomly recalculated each time the system is visited.

Secondary market definitions are entered in the [[shipdata.plist#market_definition|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''':

# The market definition array is searched from top to bottom for the first element matching the trade good
# The market quantity is scaled in proportion to the relative capacities for that good in the two markets.
# 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|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 [[shipdata.plist#market_capacity|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 [[shipdata.plist#market_monitored|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.

=== Links ===
*[https://bb.oolite.space/viewtopic.php?f=2&t=21512 Secondary Market Definitions Defined] (2023)

== 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 for determining markets for new stations.

=== From the vanilla game: Rock Hermits ===
The "market_definition" 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: the Trade-goods.plist updated from the original 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;
};

}
=== A new commodity (from the trade-goods.plist inside "SW Economy") ===
"medicine" = {
"name" = "[commodity-name medicine]";
"classes" = ("oolite-consumer","oolite-medical");
"quantity_unit" = 1;
"peak_export" = 7;
"peak_import" = 0;
"price_average" = 640;
"price_economic" = 0.25;
"price_random" = 0.15;
"quantity_average" = 5;
"quantity_economic" = 1.5;
"quantity_random" = 1.0;
"legality_export" = 0;
"legality_import" = 0;
"trumble_opinion" = 0.50;
"sort_order" = 500;
"comment" = "[oolite-commodity-medicine]";
};

=== Setting an orbital main station's slaves on sale to zero ===
[[User:Phkb|Phkb]] provided this example which requires a ''planetinfo.plist'' & a new ''.js file'' - there are other ways to achieve the same result
==== 1) planetinfo.plist (to invoke the market script) ====
(in the "Config" folder)

{
"0 96" = {market_script = "digebiti_noslaves.js";};
}

==== 2) Market script: digebiti_noslaves.js ====
(in the "Scripts" folder) - note the complex name, which prevents confusion with other snippets of script

"use strict";
this.name = "digebiti_noslaves";
this.author = "Phkb";
this.copyright = "(C) 2022 Phkb";
this.licence = "CC-NC-by-SA 4.0";
this.description = "Removes slaves for sale in Digebiti";
this.version = "1.0";

this.updateLocalCommodityDefinition = function(goodDefinition, station, systemID) {
if (goodDefinition.key == "slaves" && station && station.isMainStation) {
goodDefinition.quantity = 0;
}
return goodDefinition;
}

This method will work, so long as no other OXP changes the market_script property of the Digebiti system in the same way.

=== Creating an invariant market independent of the local system economy (agricultural/industrial) ===
If you just use a market_definition in shipdata.plist for the station, then you're merely setting variations on the primary system market.

If you want the station prices to be independent of (or more loosely tied to) the system it's in, then you need to use a [[Oolite_Market_Scripts|market script]].

So what you'd have is something like this - let's say it's a hydroponics station, so it always sells food and nothing else, regardless of whether the general system economy is industrial or agricultural:

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.key == "food") {
// are we calculating the basic Oolite "food" trade good right now? If yes, set our own static prices
goodDefinition.price = 25; // 2.5 credits
goodDefinition.quantity = 80; // lots of food
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

Now ... the reason that market definitions are preferred to be mutators of the system economy is for two reasons.
1) it means you can avoid the situation where you end up with two adjacent stations with wildly different prices ... but you can of course handle that in other ways too, station positioning, restricted access, ''etc''.
2) it makes it easier to handle OXP trade goods:
- other OXPs might have added more "food" type goods, ''e.g.'' "Meat" or "Cheese"
- you can learn about those and handle them specifically

} else if (goodDefinition.key == "bobsfoodoxp_cheese") {
// set price and quantity here

... but that means a lot of keeping up with what everyone else is doing with custom goods.

The idea was that for your hydroponics station what you might do instead is something like this

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So now if another OXP adds Cheese, provided they declare it as "edible", your station will sell it in high quantities at a big discount, but you don't need to know exactly what the baseline price or quantity was set - so if a food-focused OXP was to add "Wine", "Fine Wine" and "Vintage Wine" at a range of prices and quantities, you'd be automatically handling those in reasonable line with a combination of the Wine OXP's basic pricing structure and your station OXP's "food primary source market" style, without necessarily needing to know about every future Wine OXP there might be and explicitly set compatibility.

Note in this example we're still zeroing out all non-food goods - OXP included! - regardless of the local economy. Maybe at this point we'd want to include and document a "hydroponicsoxp-agriculturalequipment" trade good class that other OXPs could use, which this station would buy up at higher demand and prices than normal.

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else if (goodDefinition.classes.indexOf("hydroponicsoxp-agriculturalequipment") >= 0) {
// custom class for other OXPs to add specific agricultural equipment e.g. combine harvesters, compost, fertiliser
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.capacity = 16; // buy a small amount only // TODO: raise capacity if price per tonne is low
goodDefinition.quantity = 0; // not selling this
} else if (goodDefinition.key == "machinery") {
// the basic Oolite Machinery commodity isn't in the custom class but we need to buy something if
// no OXPs adding it are installed
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.quantity = 0; // not selling
goodDefinition.capacity = 16; // small capacity to buy
} else {
// don't buy or sell any other commodity
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So you can see this one has a mix of using, mutating and overruling the definitions set by the system market and OXP commodity definitions ... with this method you could have a whole bunch of OXPs setting up themed stations, and a whole different bunch adding their own custom commodities, and they'd barely have to know about each other to ensure reasonable consistency and compatibility from someone installing any combination of them. (- by [[User:Cim|Cim]], 2023)

Note: this gives examples for 1 commodity at a time, but not how to easily do that for ALL the commodities on ALL the extra stations in a system.

== Using the trade-goods.plist ==
The trade-goods.plist was designed to make commodities simpler, by:
:1) Making it a dictionary rather than an unlabelled array so one could tell which parameter was which
:2) Making the price range for a trade good dependent on more sensible variables, so rather than setting the price range with a bitmask, one set the price and quantity variations dependent on the economy and on random chance.

Compare the v.1.81 trade-goods.plist with a v.1.80 commodities.plist - they were designed to give near-identical market behaviour for the built-in trade goods.

But - that only made it more comprehensible. It didn't really let one do anything particularly different to Elite 84 markets - mostly including the "Rich Industrial -> Poor Agricultural" single spectrum. One can tweak that a bit with peak_export and peak_import to get slightly different shapes (so a good might peak at Poor Industrial rather than Rich Industrial) but it doesn't really give one the option of a third economy type still.

''So how does one introduce a new economic pole, such as a mining industry?''

For that, one needs the scripting support. [[Oolite JavaScript Reference: Market Scripts]]. 
One can quite literally do whatever one likes with the prices that way. One could have every *system* have its own separate economy, which varied over time according to events, what the player had previously traded, ''etc. etc.'' to produce something comparable to Elite Dangerous' economic sim, if that's the route one wanted to go down. Obviously the more complexity one adds the harder it gets to script up, but it's now all possible.

[[File:SOTL Altmap F8.png|thumb|right|200px|SOTL Altmap F8 commodities market]]
[[SOTL Altmap]] does have an example of it, which basically throws out the original Elite-like algorithm of trade-goods.plist and starts over. It goes *way* beyond just adding a third economy, too.

Basically in SOTL every trade good is tagged in the trade-goods.plist with a bunch of classes
''e.g.''
classes = ("sotl-ex-salvage","sotl-im-refining","sotl-quantity-high","sotl-priceband-3","sotl-demand-medium","sotl-supply-medium","sotl-volatility-low");
So that means:
- exported by salvage economies
- imported by refining economies
- high quantity, moderate price, low price volatility

Then the market script uses those classes, rather than the standard pricing variables, to define the economic behaviour.
:So line 69-74ish: get the current economy description, convert that to the format used in the class name
:...line 85-90: check for the import and export classes for that economy and see if it's imported or exported
:...lines 100-120: apply various special conditions, so e.g. the sotl-ims-radiation class checks the planet surface radiation levels (custom property in sysinfo) and if the radiation level is high, imports these goods even if the basic economy isn't interested (e.g. "sotl-ceramics-ind" in the plist)
:...and then it uses those calculations (and a bunch more of the classes) in the rest of the script to set the price and quantity depending on whether it's an import, an export, or neither

That's massive overkill for just adding a third mining economy, but one would need to work on a similar principle.

:1) Tag every commodity with classes for (import|export|none)-(agricultural|industrial|mining) as appropriate
:2) Adjust the economy names (there are a few different ways one could do that) so that the 8 economy IDs were allocated to agricultural, industrial and mining economies
:3) Have a price script which like the SOTL one gets the current economy, looks at the classes list to find out if the commodity is imported or exported or neither, and sets the price and quantity accordingly. One could use the standard price_economic, price_average, price_random properties in the plist to give baseline data to the script if one was not planning to do anything too weird.

{Technically one doesn't need the classes - just have the price script contain a list of goods internally for each economy - but this way if other people add extra trade goods in their own OXPs, they can tag them up for mining economy support too}

All fairly straightforward theoretically.

''The biggest impediment to doing a wholesale reworking of the economic system, is just how incompatible it makes lots and lots of OXP's. In order to override the vanilla commodities as in SOTL, requires setting a script for each in trade-goods.plist. Which is fine if it's the only OXP that wants to play around with commodity prices. As soon as two OXP's try to do the same thing, one gets a conflict and no longer knows which OXP pricing model is in play.''

''For SOTL it's fine, because it uses the scenario system to forcibly eject all other OXP's from use while it's running. But if one wants the OXP to go in the general playing pool set of OXP's, it becomes much more complicated. [[User:Phkb|Phkb]] spent a long time trying to work out why his market script wasn't running, only to find that [[UPS Courier]] was quietly adjusting the markets in certain systems via the planetinfo.plist file. And there are a lot of OXP's that want to play in this space, tweaking prices up or down.''

''Hence one usually abandons using any of the script options, and just tweaks the price after all the scripts have finished playing, ''eg'' in [[Smugglers]]. It was the only way to guarantee getting some sort of bump in a price when wanted.''

== Links ==
*[[Oolite JavaScript Reference: Market Scripts]]
*[[Commodities.plist]] - the precursor (which still mostly works!). If it doesn't see [https://bb.oolite.space/viewtopic.php?p=246145#p246145 here] (2015)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16828 Proposal for 1.82: support for economic changes] ([[User:Cim|Cim]], 2014)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16735 Cim on introducing the Trade-goods.plist and deprecating the commodities.plist] (2014)
{{QuoteText|Text=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.|Source=([https://bb.oolite.space/viewtopic.php?p=226722#p226722 Cim in Progress Thread (2014)])}}
=== Using the Trade-goods.plist ===
*[https://bb.oolite.space/viewtopic.php?f=4&t=20576 How to get the displayName for a commodity in the Main Station Market?] (2020)
*[https://bb.oolite.space/viewtopic.php?f=6&t=17269 Thinking about Planet Income classification] (2015)

{{QuoteText|Text=
In 1.81 this is a lot easier to OXP - you can introduce as many economies as you like, though you are limited to eight economy symbols (so if you wanted lots of economy types, you might end up with Poor Industrial, Avg Industrial and Rich Industrial sharing a symbol on the map). The trade good pricing scripts can then be used to set up different price categories in different economies (and introduce additional trade goods, or split an existing good into multiple categories, which may be necessary if you're adding more economies).

Resetting economies across the planets is a big change in terms of lines of code, but is also very easy to automate. If OXPers are looking for a scripting tool to use for this sort of automation, then NodeJS or io.js is free and also uses Javascript as its language, so you don't need to learn a new one - and may even be able to share code between your build scripts and your OXP, though I haven't tried that yet.|Source=([https://bb.oolite.space/viewtopic.php?f=6&t=17269 Cim in Planet Income thread (2015)])}}

== Preamble ==
To tweak the pricing/availability of commodities in (''eg''.) a station, you need to define the market inside the station's Shipdata.plist - or include a "hook" inside that shipdata.plist to a javascript Oolite Market Script (which allows more complex definitions).

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:

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

== Handlers ==

=== updateGeneralCommodityDefinition ===
{{oolite-method-added|1.81}}
function updateGeneralCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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 = <code>false</code> 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 ===
{{oolite-method-added|1.81}}
function updateLocalCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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.

[https://bb.oolite.space/viewtopic.php?f=4&t=17621#p239979 Here is an example] of how to use this method.

== Links ==

=== Examples ===
*Phkb's update of [[SW_Economy]] (v.3.10) creates new economies for "mining worlds" (hewn out from some low tech poor agricultural worlds) with utterly different price scales for mineral, agricultural & industrial goods, as well as medicine.

''These others will be found at the bottom of the wiki page on the'' [[Trade-goods.plist]].
*Setting an orbital main station's slaves on sale to zero
*Creating an invariant market independent of the local system economy (agricultural/industrial)

Trade-goods (abridged)

2026-06-19T15:05:58Z

Wildeblood: /* quantity_unit */

'''You are probably looking for [[Trade-goods.plist]]''', rather than this page.

[[File:Distant Riches.png|thumb|right|200px|MORE THAN FIFTY NEW TRADE GOODS]]

== F.A.Q. ==

The goal of this page is to answer the following questions.

=== How many different places can market influences be hiding? ===

In plists, in market scripts, and in station methods in ''any damned script''.

==== Which plists exactly? ====

At least trade-goods.plist , shipdata.plist , shipdata-overrides.plist , planetinfo.plist can set '''market definitions''' directly.

At least trade-goods.plist , shipdata.plist , shipdata-overrides.plist , planetinfo.plist can set links to '''market scripts'''.

==== Which market scripts exactly? ====

See below.

==== What methods might lurk in ''any damned script''? ====

station.setMarketPrice() or
station.setMarketQuantity()

=== How do we define a new "trade-good" (commodity) '''non-bogusly?''' ===

With trade-goods.plist

=== How will sub-standard OXPs thwart us? ===

By careless use of "default" in market influences to destroy things they don't even know exist.

==== Can we move the world-script in AristoShares OXP into a market script? ====

That would prevent deadbeat scripts from interfering with it. Good idea, research required.

=== Can we define new properties for commodities? ===

Where can we set "aita_image" values?

=== Is the economy 0<->7 dipole set in stone? ===

Does it really require javascript to overcome this?

If so, what is the actual function of the peak_import & peak_export properties?

== Preamble ==

The trade-goods.plist file defines "trade goods" (commodities/cargo). But, it does not ''e.g.'' remove slaves from a particular station or make them cost twice as much as they do at the main orbital station. To do such things, ''i.e.'' to tweak the pricing/availability of commodities in a particular station, you need to define the market inside that station, either within its [[Shipdata.plist]] or within a [[Oolite_Market_Scripts|market script]] linked from its shipdata.plist.

== Overview ==

The '''trade-goods.plist''' file is a dictionary of dictionaries, with (canonical) commodity names as keys to dictionaries of key-value pairs 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 (listed thematically, not alphabetically) ==

=== classes ===
An array of commodity class names. Classes can be used by secondary stations (only secondary markets?) to set pricing rules for groups of commodities.

=== market_script ===
The name of a Javascript file to use as a [[Oolite Market Scripts|market script]] for this trade good when calculating main station quantities and prices.

'''Note:''' [https://bb.oolite.space/viewtopic.php?p=235837#p235837 What's the difference between the market script specified in planetinfo.plist and the one called for by trade-goods.plist?] (2015)

=== Display on market screens ===

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

==== comment ====
A string that will be displayed on the F8 F8 commodity detail screen to describe the commodity. This can be modified later by [[Oolite_JavaScript_Reference:_Manifest#setComment|manifest.setComment()]]

==== 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 [[Oolite_JavaScript_Reference:_Manifest#setShortComment|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.

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

=== 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.

=== Legality ===

==== 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.

=== Economic biases ===

==== 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.

=== 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.

=== Quantities ===

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

==== 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.''' (Is this true? ''cf.'' Thargoidifier)

==== 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.

=== Discussion of classes ===

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)

== Secondary Market Definitions ==

The primary market is that of the system's main station (''i.e.'' the javascript object system.mainStation.market ) Secondary markets are other markets, which are influenced by the primary market, ''e.g.'' that of a local Rock Hermit, or a visiting liner or another orbital station. Both quantities and prices will be influenced by those of the primary market. Needless to say, the primary market is randomly recalculated each time the system is visited.

Secondary market definitions are entered in the [[shipdata.plist#market_definition|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''':

# The market definition array is searched from top to bottom for the first element matching the trade good
# The market quantity is scaled in proportion to the relative capacities for that good in the two markets.
# 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|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 [[shipdata.plist#market_capacity|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 [[shipdata.plist#market_monitored|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.

=== Links ===
*[https://bb.oolite.space/viewtopic.php?f=2&t=21512 Secondary Market Definitions Defined] (2023)

== 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 for determining markets for new stations.

=== From the vanilla game: Rock Hermits ===
The "market_definition" 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: the Trade-goods.plist updated from the original 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;
};

}
=== A new commodity (from the trade-goods.plist inside "SW Economy") ===
"medicine" = {
"name" = "[commodity-name medicine]";
"classes" = ("oolite-consumer","oolite-medical");
"quantity_unit" = 1;
"peak_export" = 7;
"peak_import" = 0;
"price_average" = 640;
"price_economic" = 0.25;
"price_random" = 0.15;
"quantity_average" = 5;
"quantity_economic" = 1.5;
"quantity_random" = 1.0;
"legality_export" = 0;
"legality_import" = 0;
"trumble_opinion" = 0.50;
"sort_order" = 500;
"comment" = "[oolite-commodity-medicine]";
};

=== Setting an orbital main station's slaves on sale to zero ===
[[User:Phkb|Phkb]] provided this example which requires a ''planetinfo.plist'' & a new ''.js file'' - there are other ways to achieve the same result
==== 1) planetinfo.plist (to invoke the market script) ====
(in the "Config" folder)

{
"0 96" = {market_script = "digebiti_noslaves.js";};
}

==== 2) Market script: digebiti_noslaves.js ====
(in the "Scripts" folder) - note the complex name, which prevents confusion with other snippets of script

"use strict";
this.name = "digebiti_noslaves";
this.author = "Phkb";
this.copyright = "(C) 2022 Phkb";
this.licence = "CC-NC-by-SA 4.0";
this.description = "Removes slaves for sale in Digebiti";
this.version = "1.0";

this.updateLocalCommodityDefinition = function(goodDefinition, station, systemID) {
if (goodDefinition.key == "slaves" && station && station.isMainStation) {
goodDefinition.quantity = 0;
}
return goodDefinition;
}

This method will work, so long as no other OXP changes the market_script property of the Digebiti system in the same way.

=== Creating an invariant market independent of the local system economy (agricultural/industrial) ===
If you just use a market_definition in shipdata.plist for the station, then you're merely setting variations on the primary system market.

If you want the station prices to be independent of (or more loosely tied to) the system it's in, then you need to use a [[Oolite_Market_Scripts|market script]].

So what you'd have is something like this - let's say it's a hydroponics station, so it always sells food and nothing else, regardless of whether the general system economy is industrial or agricultural:

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.key == "food") {
// are we calculating the basic Oolite "food" trade good right now? If yes, set our own static prices
goodDefinition.price = 25; // 2.5 credits
goodDefinition.quantity = 80; // lots of food
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

Now ... the reason that market definitions are preferred to be mutators of the system economy is for two reasons.
1) it means you can avoid the situation where you end up with two adjacent stations with wildly different prices ... but you can of course handle that in other ways too, station positioning, restricted access, ''etc''.
2) it makes it easier to handle OXP trade goods:
- other OXPs might have added more "food" type goods, ''e.g.'' "Meat" or "Cheese"
- you can learn about those and handle them specifically

} else if (goodDefinition.key == "bobsfoodoxp_cheese") {
// set price and quantity here

... but that means a lot of keeping up with what everyone else is doing with custom goods.

The idea was that for your hydroponics station what you might do instead is something like this

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So now if another OXP adds Cheese, provided they declare it as "edible", your station will sell it in high quantities at a big discount, but you don't need to know exactly what the baseline price or quantity was set - so if a food-focused OXP was to add "Wine", "Fine Wine" and "Vintage Wine" at a range of prices and quantities, you'd be automatically handling those in reasonable line with a combination of the Wine OXP's basic pricing structure and your station OXP's "food primary source market" style, without necessarily needing to know about every future Wine OXP there might be and explicitly set compatibility.

Note in this example we're still zeroing out all non-food goods - OXP included! - regardless of the local economy. Maybe at this point we'd want to include and document a "hydroponicsoxp-agriculturalequipment" trade good class that other OXPs could use, which this station would buy up at higher demand and prices than normal.

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else if (goodDefinition.classes.indexOf("hydroponicsoxp-agriculturalequipment") >= 0) {
// custom class for other OXPs to add specific agricultural equipment e.g. combine harvesters, compost, fertiliser
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.capacity = 16; // buy a small amount only // TODO: raise capacity if price per tonne is low
goodDefinition.quantity = 0; // not selling this
} else if (goodDefinition.key == "machinery") {
// the basic Oolite Machinery commodity isn't in the custom class but we need to buy something if
// no OXPs adding it are installed
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.quantity = 0; // not selling
goodDefinition.capacity = 16; // small capacity to buy
} else {
// don't buy or sell any other commodity
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So you can see this one has a mix of using, mutating and overruling the definitions set by the system market and OXP commodity definitions ... with this method you could have a whole bunch of OXPs setting up themed stations, and a whole different bunch adding their own custom commodities, and they'd barely have to know about each other to ensure reasonable consistency and compatibility from someone installing any combination of them. (- by [[User:Cim|Cim]], 2023)

Note: this gives examples for 1 commodity at a time, but not how to easily do that for ALL the commodities on ALL the extra stations in a system.

== Using the trade-goods.plist ==
The trade-goods.plist was designed to make commodities simpler, by:
:1) Making it a dictionary rather than an unlabelled array so one could tell which parameter was which
:2) Making the price range for a trade good dependent on more sensible variables, so rather than setting the price range with a bitmask, one set the price and quantity variations dependent on the economy and on random chance.

Compare the v.1.81 trade-goods.plist with a v.1.80 commodities.plist - they were designed to give near-identical market behaviour for the built-in trade goods.

But - that only made it more comprehensible. It didn't really let one do anything particularly different to Elite 84 markets - mostly including the "Rich Industrial -> Poor Agricultural" single spectrum. One can tweak that a bit with peak_export and peak_import to get slightly different shapes (so a good might peak at Poor Industrial rather than Rich Industrial) but it doesn't really give one the option of a third economy type still.

''So how does one introduce a new economic pole, such as a mining industry?''

For that, one needs the scripting support. [[Oolite JavaScript Reference: Market Scripts]]. 
One can quite literally do whatever one likes with the prices that way. One could have every *system* have its own separate economy, which varied over time according to events, what the player had previously traded, ''etc. etc.'' to produce something comparable to Elite Dangerous' economic sim, if that's the route one wanted to go down. Obviously the more complexity one adds the harder it gets to script up, but it's now all possible.

[[File:SOTL Altmap F8.png|thumb|right|200px|SOTL Altmap F8 commodities market]]
[[SOTL Altmap]] does have an example of it, which basically throws out the original Elite-like algorithm of trade-goods.plist and starts over. It goes *way* beyond just adding a third economy, too.

Basically in SOTL every trade good is tagged in the trade-goods.plist with a bunch of classes
''e.g.''
classes = ("sotl-ex-salvage","sotl-im-refining","sotl-quantity-high","sotl-priceband-3","sotl-demand-medium","sotl-supply-medium","sotl-volatility-low");
So that means:
- exported by salvage economies
- imported by refining economies
- high quantity, moderate price, low price volatility

Then the market script uses those classes, rather than the standard pricing variables, to define the economic behaviour.
:So line 69-74ish: get the current economy description, convert that to the format used in the class name
:...line 85-90: check for the import and export classes for that economy and see if it's imported or exported
:...lines 100-120: apply various special conditions, so e.g. the sotl-ims-radiation class checks the planet surface radiation levels (custom property in sysinfo) and if the radiation level is high, imports these goods even if the basic economy isn't interested (e.g. "sotl-ceramics-ind" in the plist)
:...and then it uses those calculations (and a bunch more of the classes) in the rest of the script to set the price and quantity depending on whether it's an import, an export, or neither

That's massive overkill for just adding a third mining economy, but one would need to work on a similar principle.

:1) Tag every commodity with classes for (import|export|none)-(agricultural|industrial|mining) as appropriate
:2) Adjust the economy names (there are a few different ways one could do that) so that the 8 economy IDs were allocated to agricultural, industrial and mining economies
:3) Have a price script which like the SOTL one gets the current economy, looks at the classes list to find out if the commodity is imported or exported or neither, and sets the price and quantity accordingly. One could use the standard price_economic, price_average, price_random properties in the plist to give baseline data to the script if one was not planning to do anything too weird.

{Technically one doesn't need the classes - just have the price script contain a list of goods internally for each economy - but this way if other people add extra trade goods in their own OXPs, they can tag them up for mining economy support too}

All fairly straightforward theoretically.

''The biggest impediment to doing a wholesale reworking of the economic system, is just how incompatible it makes lots and lots of OXP's. In order to override the vanilla commodities as in SOTL, requires setting a script for each in trade-goods.plist. Which is fine if it's the only OXP that wants to play around with commodity prices. As soon as two OXP's try to do the same thing, one gets a conflict and no longer knows which OXP pricing model is in play.''

''For SOTL it's fine, because it uses the scenario system to forcibly eject all other OXP's from use while it's running. But if one wants the OXP to go in the general playing pool set of OXP's, it becomes much more complicated. [[User:Phkb|Phkb]] spent a long time trying to work out why his market script wasn't running, only to find that [[UPS Courier]] was quietly adjusting the markets in certain systems via the planetinfo.plist file. And there are a lot of OXP's that want to play in this space, tweaking prices up or down.''

''Hence one usually abandons using any of the script options, and just tweaks the price after all the scripts have finished playing, ''eg'' in [[Smugglers]]. It was the only way to guarantee getting some sort of bump in a price when wanted.''

== Links ==
*[[Oolite JavaScript Reference: Market Scripts]]
*[[Commodities.plist]] - the precursor (which still mostly works!). If it doesn't see [https://bb.oolite.space/viewtopic.php?p=246145#p246145 here] (2015)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16828 Proposal for 1.82: support for economic changes] ([[User:Cim|Cim]], 2014)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16735 Cim on introducing the Trade-goods.plist and deprecating the commodities.plist] (2014)
{{QuoteText|Text=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.|Source=([https://bb.oolite.space/viewtopic.php?p=226722#p226722 Cim in Progress Thread (2014)])}}
=== Using the Trade-goods.plist ===
*[https://bb.oolite.space/viewtopic.php?f=4&t=20576 How to get the displayName for a commodity in the Main Station Market?] (2020)
*[https://bb.oolite.space/viewtopic.php?f=6&t=17269 Thinking about Planet Income classification] (2015)

{{QuoteText|Text=
In 1.81 this is a lot easier to OXP - you can introduce as many economies as you like, though you are limited to eight economy symbols (so if you wanted lots of economy types, you might end up with Poor Industrial, Avg Industrial and Rich Industrial sharing a symbol on the map). The trade good pricing scripts can then be used to set up different price categories in different economies (and introduce additional trade goods, or split an existing good into multiple categories, which may be necessary if you're adding more economies).

Resetting economies across the planets is a big change in terms of lines of code, but is also very easy to automate. If OXPers are looking for a scripting tool to use for this sort of automation, then NodeJS or io.js is free and also uses Javascript as its language, so you don't need to learn a new one - and may even be able to share code between your build scripts and your OXP, though I haven't tried that yet.|Source=([https://bb.oolite.space/viewtopic.php?f=6&t=17269 Cim in Planet Income thread (2015)])}}

== Preamble ==
To tweak the pricing/availability of commodities in (''eg''.) a station, you need to define the market inside the station's Shipdata.plist - or include a "hook" inside that shipdata.plist to a javascript Oolite Market Script (which allows more complex definitions).

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:

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

== Handlers ==

=== updateGeneralCommodityDefinition ===
{{oolite-method-added|1.81}}
function updateGeneralCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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 = <code>false</code> 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 ===
{{oolite-method-added|1.81}}
function updateLocalCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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.

[https://bb.oolite.space/viewtopic.php?f=4&t=17621#p239979 Here is an example] of how to use this method.

== Links ==

=== Examples ===
*Phkb's update of [[SW_Economy]] (v.3.10) creates new economies for "mining worlds" (hewn out from some low tech poor agricultural worlds) with utterly different price scales for mineral, agricultural & industrial goods, as well as medicine.

''These others will be found at the bottom of the wiki page on the'' [[Trade-goods.plist]].
*Setting an orbital main station's slaves on sale to zero
*Creating an invariant market independent of the local system economy (agricultural/industrial)

Trade-goods (abridged)

2026-06-19T14:58:26Z

Wildeblood: /* Property keys (listed thematically, not alphabetically) */

'''You are probably looking for [[Trade-goods.plist]]''', rather than this page.

[[File:Distant Riches.png|thumb|right|200px|MORE THAN FIFTY NEW TRADE GOODS]]

== F.A.Q. ==

The goal of this page is to answer the following questions.

=== How many different places can market influences be hiding? ===

In plists, in market scripts, and in station methods in ''any damned script''.

==== Which plists exactly? ====

At least trade-goods.plist , shipdata.plist , shipdata-overrides.plist , planetinfo.plist can set '''market definitions''' directly.

At least trade-goods.plist , shipdata.plist , shipdata-overrides.plist , planetinfo.plist can set links to '''market scripts'''.

==== Which market scripts exactly? ====

See below.

==== What methods might lurk in ''any damned script''? ====

station.setMarketPrice() or
station.setMarketQuantity()

=== How do we define a new "trade-good" (commodity) '''non-bogusly?''' ===

With trade-goods.plist

=== How will sub-standard OXPs thwart us? ===

By careless use of "default" in market influences to destroy things they don't even know exist.

==== Can we move the world-script in AristoShares OXP into a market script? ====

That would prevent deadbeat scripts from interfering with it. Good idea, research required.

=== Can we define new properties for commodities? ===

Where can we set "aita_image" values?

=== Is the economy 0<->7 dipole set in stone? ===

Does it really require javascript to overcome this?

If so, what is the actual function of the peak_import & peak_export properties?

== Preamble ==

The trade-goods.plist file defines "trade goods" (commodities/cargo). But, it does not ''e.g.'' remove slaves from a particular station or make them cost twice as much as they do at the main orbital station. To do such things, ''i.e.'' to tweak the pricing/availability of commodities in a particular station, you need to define the market inside that station, either within its [[Shipdata.plist]] or within a [[Oolite_Market_Scripts|market script]] linked from its shipdata.plist.

== Overview ==

The '''trade-goods.plist''' file is a dictionary of dictionaries, with (canonical) commodity names as keys to dictionaries of key-value pairs 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 (listed thematically, not alphabetically) ==

=== classes ===
An array of commodity class names. Classes can be used by secondary stations (only secondary markets?) to set pricing rules for groups of commodities.

=== market_script ===
The name of a Javascript file to use as a [[Oolite Market Scripts|market script]] for this trade good when calculating main station quantities and prices.

'''Note:''' [https://bb.oolite.space/viewtopic.php?p=235837#p235837 What's the difference between the market script specified in planetinfo.plist and the one called for by trade-goods.plist?] (2015)

=== Display on market screens ===

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

==== comment ====
A string that will be displayed on the F8 F8 commodity detail screen to describe the commodity. This can be modified later by [[Oolite_JavaScript_Reference:_Manifest#setComment|manifest.setComment()]]

==== 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 [[Oolite_JavaScript_Reference:_Manifest#setShortComment|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.

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

=== 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.

=== Legality ===

==== 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.

=== Economic biases ===

==== 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.

=== 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.

=== Quantities ===

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

==== 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.''' (Is this true? ''cf.'' Thargoidifier)

==== 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.

=== Discussion of classes ===

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)

== Secondary Market Definitions ==

The primary market is that of the system's main station (''i.e.'' the javascript object system.mainStation.market ) Secondary markets are other markets, which are influenced by the primary market, ''e.g.'' that of a local Rock Hermit, or a visiting liner or another orbital station. Both quantities and prices will be influenced by those of the primary market. Needless to say, the primary market is randomly recalculated each time the system is visited.

Secondary market definitions are entered in the [[shipdata.plist#market_definition|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''':

# The market definition array is searched from top to bottom for the first element matching the trade good
# The market quantity is scaled in proportion to the relative capacities for that good in the two markets.
# 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|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 [[shipdata.plist#market_capacity|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 [[shipdata.plist#market_monitored|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.

=== Links ===
*[https://bb.oolite.space/viewtopic.php?f=2&t=21512 Secondary Market Definitions Defined] (2023)

== 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 for determining markets for new stations.

=== From the vanilla game: Rock Hermits ===
The "market_definition" 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: the Trade-goods.plist updated from the original 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;
};

}
=== A new commodity (from the trade-goods.plist inside "SW Economy") ===
"medicine" = {
"name" = "[commodity-name medicine]";
"classes" = ("oolite-consumer","oolite-medical");
"quantity_unit" = 1;
"peak_export" = 7;
"peak_import" = 0;
"price_average" = 640;
"price_economic" = 0.25;
"price_random" = 0.15;
"quantity_average" = 5;
"quantity_economic" = 1.5;
"quantity_random" = 1.0;
"legality_export" = 0;
"legality_import" = 0;
"trumble_opinion" = 0.50;
"sort_order" = 500;
"comment" = "[oolite-commodity-medicine]";
};

=== Setting an orbital main station's slaves on sale to zero ===
[[User:Phkb|Phkb]] provided this example which requires a ''planetinfo.plist'' & a new ''.js file'' - there are other ways to achieve the same result
==== 1) planetinfo.plist (to invoke the market script) ====
(in the "Config" folder)

{
"0 96" = {market_script = "digebiti_noslaves.js";};
}

==== 2) Market script: digebiti_noslaves.js ====
(in the "Scripts" folder) - note the complex name, which prevents confusion with other snippets of script

"use strict";
this.name = "digebiti_noslaves";
this.author = "Phkb";
this.copyright = "(C) 2022 Phkb";
this.licence = "CC-NC-by-SA 4.0";
this.description = "Removes slaves for sale in Digebiti";
this.version = "1.0";

this.updateLocalCommodityDefinition = function(goodDefinition, station, systemID) {
if (goodDefinition.key == "slaves" && station && station.isMainStation) {
goodDefinition.quantity = 0;
}
return goodDefinition;
}

This method will work, so long as no other OXP changes the market_script property of the Digebiti system in the same way.

=== Creating an invariant market independent of the local system economy (agricultural/industrial) ===
If you just use a market_definition in shipdata.plist for the station, then you're merely setting variations on the primary system market.

If you want the station prices to be independent of (or more loosely tied to) the system it's in, then you need to use a [[Oolite_Market_Scripts|market script]].

So what you'd have is something like this - let's say it's a hydroponics station, so it always sells food and nothing else, regardless of whether the general system economy is industrial or agricultural:

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.key == "food") {
// are we calculating the basic Oolite "food" trade good right now? If yes, set our own static prices
goodDefinition.price = 25; // 2.5 credits
goodDefinition.quantity = 80; // lots of food
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

Now ... the reason that market definitions are preferred to be mutators of the system economy is for two reasons.
1) it means you can avoid the situation where you end up with two adjacent stations with wildly different prices ... but you can of course handle that in other ways too, station positioning, restricted access, ''etc''.
2) it makes it easier to handle OXP trade goods:
- other OXPs might have added more "food" type goods, ''e.g.'' "Meat" or "Cheese"
- you can learn about those and handle them specifically

} else if (goodDefinition.key == "bobsfoodoxp_cheese") {
// set price and quantity here

... but that means a lot of keeping up with what everyone else is doing with custom goods.

The idea was that for your hydroponics station what you might do instead is something like this

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So now if another OXP adds Cheese, provided they declare it as "edible", your station will sell it in high quantities at a big discount, but you don't need to know exactly what the baseline price or quantity was set - so if a food-focused OXP was to add "Wine", "Fine Wine" and "Vintage Wine" at a range of prices and quantities, you'd be automatically handling those in reasonable line with a combination of the Wine OXP's basic pricing structure and your station OXP's "food primary source market" style, without necessarily needing to know about every future Wine OXP there might be and explicitly set compatibility.

Note in this example we're still zeroing out all non-food goods - OXP included! - regardless of the local economy. Maybe at this point we'd want to include and document a "hydroponicsoxp-agriculturalequipment" trade good class that other OXPs could use, which this station would buy up at higher demand and prices than normal.

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else if (goodDefinition.classes.indexOf("hydroponicsoxp-agriculturalequipment") >= 0) {
// custom class for other OXPs to add specific agricultural equipment e.g. combine harvesters, compost, fertiliser
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.capacity = 16; // buy a small amount only // TODO: raise capacity if price per tonne is low
goodDefinition.quantity = 0; // not selling this
} else if (goodDefinition.key == "machinery") {
// the basic Oolite Machinery commodity isn't in the custom class but we need to buy something if
// no OXPs adding it are installed
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.quantity = 0; // not selling
goodDefinition.capacity = 16; // small capacity to buy
} else {
// don't buy or sell any other commodity
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So you can see this one has a mix of using, mutating and overruling the definitions set by the system market and OXP commodity definitions ... with this method you could have a whole bunch of OXPs setting up themed stations, and a whole different bunch adding their own custom commodities, and they'd barely have to know about each other to ensure reasonable consistency and compatibility from someone installing any combination of them. (- by [[User:Cim|Cim]], 2023)

Note: this gives examples for 1 commodity at a time, but not how to easily do that for ALL the commodities on ALL the extra stations in a system.

== Using the trade-goods.plist ==
The trade-goods.plist was designed to make commodities simpler, by:
:1) Making it a dictionary rather than an unlabelled array so one could tell which parameter was which
:2) Making the price range for a trade good dependent on more sensible variables, so rather than setting the price range with a bitmask, one set the price and quantity variations dependent on the economy and on random chance.

Compare the v.1.81 trade-goods.plist with a v.1.80 commodities.plist - they were designed to give near-identical market behaviour for the built-in trade goods.

But - that only made it more comprehensible. It didn't really let one do anything particularly different to Elite 84 markets - mostly including the "Rich Industrial -> Poor Agricultural" single spectrum. One can tweak that a bit with peak_export and peak_import to get slightly different shapes (so a good might peak at Poor Industrial rather than Rich Industrial) but it doesn't really give one the option of a third economy type still.

''So how does one introduce a new economic pole, such as a mining industry?''

For that, one needs the scripting support. [[Oolite JavaScript Reference: Market Scripts]]. 
One can quite literally do whatever one likes with the prices that way. One could have every *system* have its own separate economy, which varied over time according to events, what the player had previously traded, ''etc. etc.'' to produce something comparable to Elite Dangerous' economic sim, if that's the route one wanted to go down. Obviously the more complexity one adds the harder it gets to script up, but it's now all possible.

[[File:SOTL Altmap F8.png|thumb|right|200px|SOTL Altmap F8 commodities market]]
[[SOTL Altmap]] does have an example of it, which basically throws out the original Elite-like algorithm of trade-goods.plist and starts over. It goes *way* beyond just adding a third economy, too.

Basically in SOTL every trade good is tagged in the trade-goods.plist with a bunch of classes
''e.g.''
classes = ("sotl-ex-salvage","sotl-im-refining","sotl-quantity-high","sotl-priceband-3","sotl-demand-medium","sotl-supply-medium","sotl-volatility-low");
So that means:
- exported by salvage economies
- imported by refining economies
- high quantity, moderate price, low price volatility

Then the market script uses those classes, rather than the standard pricing variables, to define the economic behaviour.
:So line 69-74ish: get the current economy description, convert that to the format used in the class name
:...line 85-90: check for the import and export classes for that economy and see if it's imported or exported
:...lines 100-120: apply various special conditions, so e.g. the sotl-ims-radiation class checks the planet surface radiation levels (custom property in sysinfo) and if the radiation level is high, imports these goods even if the basic economy isn't interested (e.g. "sotl-ceramics-ind" in the plist)
:...and then it uses those calculations (and a bunch more of the classes) in the rest of the script to set the price and quantity depending on whether it's an import, an export, or neither

That's massive overkill for just adding a third mining economy, but one would need to work on a similar principle.

:1) Tag every commodity with classes for (import|export|none)-(agricultural|industrial|mining) as appropriate
:2) Adjust the economy names (there are a few different ways one could do that) so that the 8 economy IDs were allocated to agricultural, industrial and mining economies
:3) Have a price script which like the SOTL one gets the current economy, looks at the classes list to find out if the commodity is imported or exported or neither, and sets the price and quantity accordingly. One could use the standard price_economic, price_average, price_random properties in the plist to give baseline data to the script if one was not planning to do anything too weird.

{Technically one doesn't need the classes - just have the price script contain a list of goods internally for each economy - but this way if other people add extra trade goods in their own OXPs, they can tag them up for mining economy support too}

All fairly straightforward theoretically.

''The biggest impediment to doing a wholesale reworking of the economic system, is just how incompatible it makes lots and lots of OXP's. In order to override the vanilla commodities as in SOTL, requires setting a script for each in trade-goods.plist. Which is fine if it's the only OXP that wants to play around with commodity prices. As soon as two OXP's try to do the same thing, one gets a conflict and no longer knows which OXP pricing model is in play.''

''For SOTL it's fine, because it uses the scenario system to forcibly eject all other OXP's from use while it's running. But if one wants the OXP to go in the general playing pool set of OXP's, it becomes much more complicated. [[User:Phkb|Phkb]] spent a long time trying to work out why his market script wasn't running, only to find that [[UPS Courier]] was quietly adjusting the markets in certain systems via the planetinfo.plist file. And there are a lot of OXP's that want to play in this space, tweaking prices up or down.''

''Hence one usually abandons using any of the script options, and just tweaks the price after all the scripts have finished playing, ''eg'' in [[Smugglers]]. It was the only way to guarantee getting some sort of bump in a price when wanted.''

== Links ==
*[[Oolite JavaScript Reference: Market Scripts]]
*[[Commodities.plist]] - the precursor (which still mostly works!). If it doesn't see [https://bb.oolite.space/viewtopic.php?p=246145#p246145 here] (2015)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16828 Proposal for 1.82: support for economic changes] ([[User:Cim|Cim]], 2014)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16735 Cim on introducing the Trade-goods.plist and deprecating the commodities.plist] (2014)
{{QuoteText|Text=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.|Source=([https://bb.oolite.space/viewtopic.php?p=226722#p226722 Cim in Progress Thread (2014)])}}
=== Using the Trade-goods.plist ===
*[https://bb.oolite.space/viewtopic.php?f=4&t=20576 How to get the displayName for a commodity in the Main Station Market?] (2020)
*[https://bb.oolite.space/viewtopic.php?f=6&t=17269 Thinking about Planet Income classification] (2015)

{{QuoteText|Text=
In 1.81 this is a lot easier to OXP - you can introduce as many economies as you like, though you are limited to eight economy symbols (so if you wanted lots of economy types, you might end up with Poor Industrial, Avg Industrial and Rich Industrial sharing a symbol on the map). The trade good pricing scripts can then be used to set up different price categories in different economies (and introduce additional trade goods, or split an existing good into multiple categories, which may be necessary if you're adding more economies).

Resetting economies across the planets is a big change in terms of lines of code, but is also very easy to automate. If OXPers are looking for a scripting tool to use for this sort of automation, then NodeJS or io.js is free and also uses Javascript as its language, so you don't need to learn a new one - and may even be able to share code between your build scripts and your OXP, though I haven't tried that yet.|Source=([https://bb.oolite.space/viewtopic.php?f=6&t=17269 Cim in Planet Income thread (2015)])}}

== Preamble ==
To tweak the pricing/availability of commodities in (''eg''.) a station, you need to define the market inside the station's Shipdata.plist - or include a "hook" inside that shipdata.plist to a javascript Oolite Market Script (which allows more complex definitions).

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:

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

== Handlers ==

=== updateGeneralCommodityDefinition ===
{{oolite-method-added|1.81}}
function updateGeneralCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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 = <code>false</code> 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 ===
{{oolite-method-added|1.81}}
function updateLocalCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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.

[https://bb.oolite.space/viewtopic.php?f=4&t=17621#p239979 Here is an example] of how to use this method.

== Links ==

=== Examples ===
*Phkb's update of [[SW_Economy]] (v.3.10) creates new economies for "mining worlds" (hewn out from some low tech poor agricultural worlds) with utterly different price scales for mineral, agricultural & industrial goods, as well as medicine.

''These others will be found at the bottom of the wiki page on the'' [[Trade-goods.plist]].
*Setting an orbital main station's slaves on sale to zero
*Creating an invariant market independent of the local system economy (agricultural/industrial)

Trade-goods (abridged)

2026-06-19T14:49:51Z

Wildeblood: /* sort_order */

'''You are probably looking for [[Trade-goods.plist]]''', rather than this page.

[[File:Distant Riches.png|thumb|right|200px|MORE THAN FIFTY NEW TRADE GOODS]]

== F.A.Q. ==

The goal of this page is to answer the following questions.

=== How many different places can market influences be hiding? ===

In plists, in market scripts, and in station methods in ''any damned script''.

==== Which plists exactly? ====

At least trade-goods.plist , shipdata.plist , shipdata-overrides.plist , planetinfo.plist can set '''market definitions''' directly.

At least trade-goods.plist , shipdata.plist , shipdata-overrides.plist , planetinfo.plist can set links to '''market scripts'''.

==== Which market scripts exactly? ====

See below.

==== What methods might lurk in ''any damned script''? ====

station.setMarketPrice() or
station.setMarketQuantity()

=== How do we define a new "trade-good" (commodity) '''non-bogusly?''' ===

With trade-goods.plist

=== How will sub-standard OXPs thwart us? ===

By careless use of "default" in market influences to destroy things they don't even know exist.

==== Can we move the world-script in AristoShares OXP into a market script? ====

That would prevent deadbeat scripts from interfering with it. Good idea, research required.

=== Can we define new properties for commodities? ===

Where can we set "aita_image" values?

=== Is the economy 0<->7 dipole set in stone? ===

Does it really require javascript to overcome this?

If so, what is the actual function of the peak_import & peak_export properties?

== Preamble ==

The trade-goods.plist file defines "trade goods" (commodities/cargo). But, it does not ''e.g.'' remove slaves from a particular station or make them cost twice as much as they do at the main orbital station. To do such things, ''i.e.'' to tweak the pricing/availability of commodities in a particular station, you need to define the market inside that station, either within its [[Shipdata.plist]] or within a [[Oolite_Market_Scripts|market script]] linked from its shipdata.plist.

== Overview ==

The '''trade-goods.plist''' file is a dictionary of dictionaries, with (canonical) commodity names as keys to dictionaries of key-value pairs 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 (listed thematically, not alphabetically) ==

=== Display on market screens ===

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

=== market_script ===
The name of a Javascript file to use as a [[Oolite Market Scripts|market script]] for this trade good when calculating main station quantities and prices.

'''Note:''' [https://bb.oolite.space/viewtopic.php?p=235837#p235837 What's the difference between the market script specified in planetinfo.plist and the one called for by trade-goods.plist?] (2015)

=== classes ===
An array of commodity class names. Classes can be used by secondary stations (only secondary markets?) to set pricing rules for groups of commodities.

==== comment ====
A string that will be displayed on the F8 F8 commodity detail screen to describe the commodity. This can be modified later by [[Oolite_JavaScript_Reference:_Manifest#setComment|manifest.setComment()]]

=== 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 [[Oolite_JavaScript_Reference:_Manifest#setShortComment|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.

=== Legality ===

==== 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.

=== Economic biases ===

==== 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.

=== 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.

=== Quantities ===

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

==== 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.''' (Is this true? ''cf.'' Thargoidifier)

==== 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.

=== Discussion of classes ===

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)

== Secondary Market Definitions ==

The primary market is that of the system's main station (''i.e.'' the javascript object system.mainStation.market ) Secondary markets are other markets, which are influenced by the primary market, ''e.g.'' that of a local Rock Hermit, or a visiting liner or another orbital station. Both quantities and prices will be influenced by those of the primary market. Needless to say, the primary market is randomly recalculated each time the system is visited.

Secondary market definitions are entered in the [[shipdata.plist#market_definition|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''':

# The market definition array is searched from top to bottom for the first element matching the trade good
# The market quantity is scaled in proportion to the relative capacities for that good in the two markets.
# 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|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 [[shipdata.plist#market_capacity|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 [[shipdata.plist#market_monitored|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.

=== Links ===
*[https://bb.oolite.space/viewtopic.php?f=2&t=21512 Secondary Market Definitions Defined] (2023)

== 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 for determining markets for new stations.

=== From the vanilla game: Rock Hermits ===
The "market_definition" 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: the Trade-goods.plist updated from the original 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;
};

}
=== A new commodity (from the trade-goods.plist inside "SW Economy") ===
"medicine" = {
"name" = "[commodity-name medicine]";
"classes" = ("oolite-consumer","oolite-medical");
"quantity_unit" = 1;
"peak_export" = 7;
"peak_import" = 0;
"price_average" = 640;
"price_economic" = 0.25;
"price_random" = 0.15;
"quantity_average" = 5;
"quantity_economic" = 1.5;
"quantity_random" = 1.0;
"legality_export" = 0;
"legality_import" = 0;
"trumble_opinion" = 0.50;
"sort_order" = 500;
"comment" = "[oolite-commodity-medicine]";
};

=== Setting an orbital main station's slaves on sale to zero ===
[[User:Phkb|Phkb]] provided this example which requires a ''planetinfo.plist'' & a new ''.js file'' - there are other ways to achieve the same result
==== 1) planetinfo.plist (to invoke the market script) ====
(in the "Config" folder)

{
"0 96" = {market_script = "digebiti_noslaves.js";};
}

==== 2) Market script: digebiti_noslaves.js ====
(in the "Scripts" folder) - note the complex name, which prevents confusion with other snippets of script

"use strict";
this.name = "digebiti_noslaves";
this.author = "Phkb";
this.copyright = "(C) 2022 Phkb";
this.licence = "CC-NC-by-SA 4.0";
this.description = "Removes slaves for sale in Digebiti";
this.version = "1.0";

this.updateLocalCommodityDefinition = function(goodDefinition, station, systemID) {
if (goodDefinition.key == "slaves" && station && station.isMainStation) {
goodDefinition.quantity = 0;
}
return goodDefinition;
}

This method will work, so long as no other OXP changes the market_script property of the Digebiti system in the same way.

=== Creating an invariant market independent of the local system economy (agricultural/industrial) ===
If you just use a market_definition in shipdata.plist for the station, then you're merely setting variations on the primary system market.

If you want the station prices to be independent of (or more loosely tied to) the system it's in, then you need to use a [[Oolite_Market_Scripts|market script]].

So what you'd have is something like this - let's say it's a hydroponics station, so it always sells food and nothing else, regardless of whether the general system economy is industrial or agricultural:

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.key == "food") {
// are we calculating the basic Oolite "food" trade good right now? If yes, set our own static prices
goodDefinition.price = 25; // 2.5 credits
goodDefinition.quantity = 80; // lots of food
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

Now ... the reason that market definitions are preferred to be mutators of the system economy is for two reasons.
1) it means you can avoid the situation where you end up with two adjacent stations with wildly different prices ... but you can of course handle that in other ways too, station positioning, restricted access, ''etc''.
2) it makes it easier to handle OXP trade goods:
- other OXPs might have added more "food" type goods, ''e.g.'' "Meat" or "Cheese"
- you can learn about those and handle them specifically

} else if (goodDefinition.key == "bobsfoodoxp_cheese") {
// set price and quantity here

... but that means a lot of keeping up with what everyone else is doing with custom goods.

The idea was that for your hydroponics station what you might do instead is something like this

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So now if another OXP adds Cheese, provided they declare it as "edible", your station will sell it in high quantities at a big discount, but you don't need to know exactly what the baseline price or quantity was set - so if a food-focused OXP was to add "Wine", "Fine Wine" and "Vintage Wine" at a range of prices and quantities, you'd be automatically handling those in reasonable line with a combination of the Wine OXP's basic pricing structure and your station OXP's "food primary source market" style, without necessarily needing to know about every future Wine OXP there might be and explicitly set compatibility.

Note in this example we're still zeroing out all non-food goods - OXP included! - regardless of the local economy. Maybe at this point we'd want to include and document a "hydroponicsoxp-agriculturalequipment" trade good class that other OXPs could use, which this station would buy up at higher demand and prices than normal.

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else if (goodDefinition.classes.indexOf("hydroponicsoxp-agriculturalequipment") >= 0) {
// custom class for other OXPs to add specific agricultural equipment e.g. combine harvesters, compost, fertiliser
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.capacity = 16; // buy a small amount only // TODO: raise capacity if price per tonne is low
goodDefinition.quantity = 0; // not selling this
} else if (goodDefinition.key == "machinery") {
// the basic Oolite Machinery commodity isn't in the custom class but we need to buy something if
// no OXPs adding it are installed
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.quantity = 0; // not selling
goodDefinition.capacity = 16; // small capacity to buy
} else {
// don't buy or sell any other commodity
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So you can see this one has a mix of using, mutating and overruling the definitions set by the system market and OXP commodity definitions ... with this method you could have a whole bunch of OXPs setting up themed stations, and a whole different bunch adding their own custom commodities, and they'd barely have to know about each other to ensure reasonable consistency and compatibility from someone installing any combination of them. (- by [[User:Cim|Cim]], 2023)

Note: this gives examples for 1 commodity at a time, but not how to easily do that for ALL the commodities on ALL the extra stations in a system.

== Using the trade-goods.plist ==
The trade-goods.plist was designed to make commodities simpler, by:
:1) Making it a dictionary rather than an unlabelled array so one could tell which parameter was which
:2) Making the price range for a trade good dependent on more sensible variables, so rather than setting the price range with a bitmask, one set the price and quantity variations dependent on the economy and on random chance.

Compare the v.1.81 trade-goods.plist with a v.1.80 commodities.plist - they were designed to give near-identical market behaviour for the built-in trade goods.

But - that only made it more comprehensible. It didn't really let one do anything particularly different to Elite 84 markets - mostly including the "Rich Industrial -> Poor Agricultural" single spectrum. One can tweak that a bit with peak_export and peak_import to get slightly different shapes (so a good might peak at Poor Industrial rather than Rich Industrial) but it doesn't really give one the option of a third economy type still.

''So how does one introduce a new economic pole, such as a mining industry?''

For that, one needs the scripting support. [[Oolite JavaScript Reference: Market Scripts]]. 
One can quite literally do whatever one likes with the prices that way. One could have every *system* have its own separate economy, which varied over time according to events, what the player had previously traded, ''etc. etc.'' to produce something comparable to Elite Dangerous' economic sim, if that's the route one wanted to go down. Obviously the more complexity one adds the harder it gets to script up, but it's now all possible.

[[File:SOTL Altmap F8.png|thumb|right|200px|SOTL Altmap F8 commodities market]]
[[SOTL Altmap]] does have an example of it, which basically throws out the original Elite-like algorithm of trade-goods.plist and starts over. It goes *way* beyond just adding a third economy, too.

Basically in SOTL every trade good is tagged in the trade-goods.plist with a bunch of classes
''e.g.''
classes = ("sotl-ex-salvage","sotl-im-refining","sotl-quantity-high","sotl-priceband-3","sotl-demand-medium","sotl-supply-medium","sotl-volatility-low");
So that means:
- exported by salvage economies
- imported by refining economies
- high quantity, moderate price, low price volatility

Then the market script uses those classes, rather than the standard pricing variables, to define the economic behaviour.
:So line 69-74ish: get the current economy description, convert that to the format used in the class name
:...line 85-90: check for the import and export classes for that economy and see if it's imported or exported
:...lines 100-120: apply various special conditions, so e.g. the sotl-ims-radiation class checks the planet surface radiation levels (custom property in sysinfo) and if the radiation level is high, imports these goods even if the basic economy isn't interested (e.g. "sotl-ceramics-ind" in the plist)
:...and then it uses those calculations (and a bunch more of the classes) in the rest of the script to set the price and quantity depending on whether it's an import, an export, or neither

That's massive overkill for just adding a third mining economy, but one would need to work on a similar principle.

:1) Tag every commodity with classes for (import|export|none)-(agricultural|industrial|mining) as appropriate
:2) Adjust the economy names (there are a few different ways one could do that) so that the 8 economy IDs were allocated to agricultural, industrial and mining economies
:3) Have a price script which like the SOTL one gets the current economy, looks at the classes list to find out if the commodity is imported or exported or neither, and sets the price and quantity accordingly. One could use the standard price_economic, price_average, price_random properties in the plist to give baseline data to the script if one was not planning to do anything too weird.

{Technically one doesn't need the classes - just have the price script contain a list of goods internally for each economy - but this way if other people add extra trade goods in their own OXPs, they can tag them up for mining economy support too}

All fairly straightforward theoretically.

''The biggest impediment to doing a wholesale reworking of the economic system, is just how incompatible it makes lots and lots of OXP's. In order to override the vanilla commodities as in SOTL, requires setting a script for each in trade-goods.plist. Which is fine if it's the only OXP that wants to play around with commodity prices. As soon as two OXP's try to do the same thing, one gets a conflict and no longer knows which OXP pricing model is in play.''

''For SOTL it's fine, because it uses the scenario system to forcibly eject all other OXP's from use while it's running. But if one wants the OXP to go in the general playing pool set of OXP's, it becomes much more complicated. [[User:Phkb|Phkb]] spent a long time trying to work out why his market script wasn't running, only to find that [[UPS Courier]] was quietly adjusting the markets in certain systems via the planetinfo.plist file. And there are a lot of OXP's that want to play in this space, tweaking prices up or down.''

''Hence one usually abandons using any of the script options, and just tweaks the price after all the scripts have finished playing, ''eg'' in [[Smugglers]]. It was the only way to guarantee getting some sort of bump in a price when wanted.''

== Links ==
*[[Oolite JavaScript Reference: Market Scripts]]
*[[Commodities.plist]] - the precursor (which still mostly works!). If it doesn't see [https://bb.oolite.space/viewtopic.php?p=246145#p246145 here] (2015)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16828 Proposal for 1.82: support for economic changes] ([[User:Cim|Cim]], 2014)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16735 Cim on introducing the Trade-goods.plist and deprecating the commodities.plist] (2014)
{{QuoteText|Text=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.|Source=([https://bb.oolite.space/viewtopic.php?p=226722#p226722 Cim in Progress Thread (2014)])}}
=== Using the Trade-goods.plist ===
*[https://bb.oolite.space/viewtopic.php?f=4&t=20576 How to get the displayName for a commodity in the Main Station Market?] (2020)
*[https://bb.oolite.space/viewtopic.php?f=6&t=17269 Thinking about Planet Income classification] (2015)

{{QuoteText|Text=
In 1.81 this is a lot easier to OXP - you can introduce as many economies as you like, though you are limited to eight economy symbols (so if you wanted lots of economy types, you might end up with Poor Industrial, Avg Industrial and Rich Industrial sharing a symbol on the map). The trade good pricing scripts can then be used to set up different price categories in different economies (and introduce additional trade goods, or split an existing good into multiple categories, which may be necessary if you're adding more economies).

Resetting economies across the planets is a big change in terms of lines of code, but is also very easy to automate. If OXPers are looking for a scripting tool to use for this sort of automation, then NodeJS or io.js is free and also uses Javascript as its language, so you don't need to learn a new one - and may even be able to share code between your build scripts and your OXP, though I haven't tried that yet.|Source=([https://bb.oolite.space/viewtopic.php?f=6&t=17269 Cim in Planet Income thread (2015)])}}

== Preamble ==
To tweak the pricing/availability of commodities in (''eg''.) a station, you need to define the market inside the station's Shipdata.plist - or include a "hook" inside that shipdata.plist to a javascript Oolite Market Script (which allows more complex definitions).

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:

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

== Handlers ==

=== updateGeneralCommodityDefinition ===
{{oolite-method-added|1.81}}
function updateGeneralCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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 = <code>false</code> 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 ===
{{oolite-method-added|1.81}}
function updateLocalCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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.

[https://bb.oolite.space/viewtopic.php?f=4&t=17621#p239979 Here is an example] of how to use this method.

== Links ==

=== Examples ===
*Phkb's update of [[SW_Economy]] (v.3.10) creates new economies for "mining worlds" (hewn out from some low tech poor agricultural worlds) with utterly different price scales for mineral, agricultural & industrial goods, as well as medicine.

''These others will be found at the bottom of the wiki page on the'' [[Trade-goods.plist]].
*Setting an orbital main station's slaves on sale to zero
*Creating an invariant market independent of the local system economy (agricultural/industrial)

Trade-goods (abridged)

2026-06-19T14:49:22Z

Wildeblood: /* short_comment */

'''You are probably looking for [[Trade-goods.plist]]''', rather than this page.

[[File:Distant Riches.png|thumb|right|200px|MORE THAN FIFTY NEW TRADE GOODS]]

== F.A.Q. ==

The goal of this page is to answer the following questions.

=== How many different places can market influences be hiding? ===

In plists, in market scripts, and in station methods in ''any damned script''.

==== Which plists exactly? ====

At least trade-goods.plist , shipdata.plist , shipdata-overrides.plist , planetinfo.plist can set '''market definitions''' directly.

At least trade-goods.plist , shipdata.plist , shipdata-overrides.plist , planetinfo.plist can set links to '''market scripts'''.

==== Which market scripts exactly? ====

See below.

==== What methods might lurk in ''any damned script''? ====

station.setMarketPrice() or
station.setMarketQuantity()

=== How do we define a new "trade-good" (commodity) '''non-bogusly?''' ===

With trade-goods.plist

=== How will sub-standard OXPs thwart us? ===

By careless use of "default" in market influences to destroy things they don't even know exist.

==== Can we move the world-script in AristoShares OXP into a market script? ====

That would prevent deadbeat scripts from interfering with it. Good idea, research required.

=== Can we define new properties for commodities? ===

Where can we set "aita_image" values?

=== Is the economy 0<->7 dipole set in stone? ===

Does it really require javascript to overcome this?

If so, what is the actual function of the peak_import & peak_export properties?

== Preamble ==

The trade-goods.plist file defines "trade goods" (commodities/cargo). But, it does not ''e.g.'' remove slaves from a particular station or make them cost twice as much as they do at the main orbital station. To do such things, ''i.e.'' to tweak the pricing/availability of commodities in a particular station, you need to define the market inside that station, either within its [[Shipdata.plist]] or within a [[Oolite_Market_Scripts|market script]] linked from its shipdata.plist.

== Overview ==

The '''trade-goods.plist''' file is a dictionary of dictionaries, with (canonical) commodity names as keys to dictionaries of key-value pairs 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 (listed thematically, not alphabetically) ==

=== Display on market screens ===

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

=== market_script ===
The name of a Javascript file to use as a [[Oolite Market Scripts|market script]] for this trade good when calculating main station quantities and prices.

'''Note:''' [https://bb.oolite.space/viewtopic.php?p=235837#p235837 What's the difference between the market script specified in planetinfo.plist and the one called for by trade-goods.plist?] (2015)

=== classes ===
An array of commodity class names. Classes can be used by secondary stations (only secondary markets?) to set pricing rules for groups of commodities.

==== comment ====
A string that will be displayed on the F8 F8 commodity detail screen to describe the commodity. This can be modified later by [[Oolite_JavaScript_Reference:_Manifest#setComment|manifest.setComment()]]

=== 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 [[Oolite_JavaScript_Reference:_Manifest#setShortComment|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.

=== Legality ===

==== 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.

=== Economic biases ===

==== 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.

=== 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.

=== Quantities ===

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

==== 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.''' (Is this true? ''cf.'' Thargoidifier)

==== 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.

=== Discussion of classes ===

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)

== Secondary Market Definitions ==

The primary market is that of the system's main station (''i.e.'' the javascript object system.mainStation.market ) Secondary markets are other markets, which are influenced by the primary market, ''e.g.'' that of a local Rock Hermit, or a visiting liner or another orbital station. Both quantities and prices will be influenced by those of the primary market. Needless to say, the primary market is randomly recalculated each time the system is visited.

Secondary market definitions are entered in the [[shipdata.plist#market_definition|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''':

# The market definition array is searched from top to bottom for the first element matching the trade good
# The market quantity is scaled in proportion to the relative capacities for that good in the two markets.
# 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|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 [[shipdata.plist#market_capacity|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 [[shipdata.plist#market_monitored|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.

=== Links ===
*[https://bb.oolite.space/viewtopic.php?f=2&t=21512 Secondary Market Definitions Defined] (2023)

== 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 for determining markets for new stations.

=== From the vanilla game: Rock Hermits ===
The "market_definition" 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: the Trade-goods.plist updated from the original 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;
};

}
=== A new commodity (from the trade-goods.plist inside "SW Economy") ===
"medicine" = {
"name" = "[commodity-name medicine]";
"classes" = ("oolite-consumer","oolite-medical");
"quantity_unit" = 1;
"peak_export" = 7;
"peak_import" = 0;
"price_average" = 640;
"price_economic" = 0.25;
"price_random" = 0.15;
"quantity_average" = 5;
"quantity_economic" = 1.5;
"quantity_random" = 1.0;
"legality_export" = 0;
"legality_import" = 0;
"trumble_opinion" = 0.50;
"sort_order" = 500;
"comment" = "[oolite-commodity-medicine]";
};

=== Setting an orbital main station's slaves on sale to zero ===
[[User:Phkb|Phkb]] provided this example which requires a ''planetinfo.plist'' & a new ''.js file'' - there are other ways to achieve the same result
==== 1) planetinfo.plist (to invoke the market script) ====
(in the "Config" folder)

{
"0 96" = {market_script = "digebiti_noslaves.js";};
}

==== 2) Market script: digebiti_noslaves.js ====
(in the "Scripts" folder) - note the complex name, which prevents confusion with other snippets of script

"use strict";
this.name = "digebiti_noslaves";
this.author = "Phkb";
this.copyright = "(C) 2022 Phkb";
this.licence = "CC-NC-by-SA 4.0";
this.description = "Removes slaves for sale in Digebiti";
this.version = "1.0";

this.updateLocalCommodityDefinition = function(goodDefinition, station, systemID) {
if (goodDefinition.key == "slaves" && station && station.isMainStation) {
goodDefinition.quantity = 0;
}
return goodDefinition;
}

This method will work, so long as no other OXP changes the market_script property of the Digebiti system in the same way.

=== Creating an invariant market independent of the local system economy (agricultural/industrial) ===
If you just use a market_definition in shipdata.plist for the station, then you're merely setting variations on the primary system market.

If you want the station prices to be independent of (or more loosely tied to) the system it's in, then you need to use a [[Oolite_Market_Scripts|market script]].

So what you'd have is something like this - let's say it's a hydroponics station, so it always sells food and nothing else, regardless of whether the general system economy is industrial or agricultural:

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.key == "food") {
// are we calculating the basic Oolite "food" trade good right now? If yes, set our own static prices
goodDefinition.price = 25; // 2.5 credits
goodDefinition.quantity = 80; // lots of food
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

Now ... the reason that market definitions are preferred to be mutators of the system economy is for two reasons.
1) it means you can avoid the situation where you end up with two adjacent stations with wildly different prices ... but you can of course handle that in other ways too, station positioning, restricted access, ''etc''.
2) it makes it easier to handle OXP trade goods:
- other OXPs might have added more "food" type goods, ''e.g.'' "Meat" or "Cheese"
- you can learn about those and handle them specifically

} else if (goodDefinition.key == "bobsfoodoxp_cheese") {
// set price and quantity here

... but that means a lot of keeping up with what everyone else is doing with custom goods.

The idea was that for your hydroponics station what you might do instead is something like this

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So now if another OXP adds Cheese, provided they declare it as "edible", your station will sell it in high quantities at a big discount, but you don't need to know exactly what the baseline price or quantity was set - so if a food-focused OXP was to add "Wine", "Fine Wine" and "Vintage Wine" at a range of prices and quantities, you'd be automatically handling those in reasonable line with a combination of the Wine OXP's basic pricing structure and your station OXP's "food primary source market" style, without necessarily needing to know about every future Wine OXP there might be and explicitly set compatibility.

Note in this example we're still zeroing out all non-food goods - OXP included! - regardless of the local economy. Maybe at this point we'd want to include and document a "hydroponicsoxp-agriculturalequipment" trade good class that other OXPs could use, which this station would buy up at higher demand and prices than normal.

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else if (goodDefinition.classes.indexOf("hydroponicsoxp-agriculturalequipment") >= 0) {
// custom class for other OXPs to add specific agricultural equipment e.g. combine harvesters, compost, fertiliser
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.capacity = 16; // buy a small amount only // TODO: raise capacity if price per tonne is low
goodDefinition.quantity = 0; // not selling this
} else if (goodDefinition.key == "machinery") {
// the basic Oolite Machinery commodity isn't in the custom class but we need to buy something if
// no OXPs adding it are installed
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.quantity = 0; // not selling
goodDefinition.capacity = 16; // small capacity to buy
} else {
// don't buy or sell any other commodity
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So you can see this one has a mix of using, mutating and overruling the definitions set by the system market and OXP commodity definitions ... with this method you could have a whole bunch of OXPs setting up themed stations, and a whole different bunch adding their own custom commodities, and they'd barely have to know about each other to ensure reasonable consistency and compatibility from someone installing any combination of them. (- by [[User:Cim|Cim]], 2023)

Note: this gives examples for 1 commodity at a time, but not how to easily do that for ALL the commodities on ALL the extra stations in a system.

== Using the trade-goods.plist ==
The trade-goods.plist was designed to make commodities simpler, by:
:1) Making it a dictionary rather than an unlabelled array so one could tell which parameter was which
:2) Making the price range for a trade good dependent on more sensible variables, so rather than setting the price range with a bitmask, one set the price and quantity variations dependent on the economy and on random chance.

Compare the v.1.81 trade-goods.plist with a v.1.80 commodities.plist - they were designed to give near-identical market behaviour for the built-in trade goods.

But - that only made it more comprehensible. It didn't really let one do anything particularly different to Elite 84 markets - mostly including the "Rich Industrial -> Poor Agricultural" single spectrum. One can tweak that a bit with peak_export and peak_import to get slightly different shapes (so a good might peak at Poor Industrial rather than Rich Industrial) but it doesn't really give one the option of a third economy type still.

''So how does one introduce a new economic pole, such as a mining industry?''

For that, one needs the scripting support. [[Oolite JavaScript Reference: Market Scripts]]. 
One can quite literally do whatever one likes with the prices that way. One could have every *system* have its own separate economy, which varied over time according to events, what the player had previously traded, ''etc. etc.'' to produce something comparable to Elite Dangerous' economic sim, if that's the route one wanted to go down. Obviously the more complexity one adds the harder it gets to script up, but it's now all possible.

[[File:SOTL Altmap F8.png|thumb|right|200px|SOTL Altmap F8 commodities market]]
[[SOTL Altmap]] does have an example of it, which basically throws out the original Elite-like algorithm of trade-goods.plist and starts over. It goes *way* beyond just adding a third economy, too.

Basically in SOTL every trade good is tagged in the trade-goods.plist with a bunch of classes
''e.g.''
classes = ("sotl-ex-salvage","sotl-im-refining","sotl-quantity-high","sotl-priceband-3","sotl-demand-medium","sotl-supply-medium","sotl-volatility-low");
So that means:
- exported by salvage economies
- imported by refining economies
- high quantity, moderate price, low price volatility

Then the market script uses those classes, rather than the standard pricing variables, to define the economic behaviour.
:So line 69-74ish: get the current economy description, convert that to the format used in the class name
:...line 85-90: check for the import and export classes for that economy and see if it's imported or exported
:...lines 100-120: apply various special conditions, so e.g. the sotl-ims-radiation class checks the planet surface radiation levels (custom property in sysinfo) and if the radiation level is high, imports these goods even if the basic economy isn't interested (e.g. "sotl-ceramics-ind" in the plist)
:...and then it uses those calculations (and a bunch more of the classes) in the rest of the script to set the price and quantity depending on whether it's an import, an export, or neither

That's massive overkill for just adding a third mining economy, but one would need to work on a similar principle.

:1) Tag every commodity with classes for (import|export|none)-(agricultural|industrial|mining) as appropriate
:2) Adjust the economy names (there are a few different ways one could do that) so that the 8 economy IDs were allocated to agricultural, industrial and mining economies
:3) Have a price script which like the SOTL one gets the current economy, looks at the classes list to find out if the commodity is imported or exported or neither, and sets the price and quantity accordingly. One could use the standard price_economic, price_average, price_random properties in the plist to give baseline data to the script if one was not planning to do anything too weird.

{Technically one doesn't need the classes - just have the price script contain a list of goods internally for each economy - but this way if other people add extra trade goods in their own OXPs, they can tag them up for mining economy support too}

All fairly straightforward theoretically.

''The biggest impediment to doing a wholesale reworking of the economic system, is just how incompatible it makes lots and lots of OXP's. In order to override the vanilla commodities as in SOTL, requires setting a script for each in trade-goods.plist. Which is fine if it's the only OXP that wants to play around with commodity prices. As soon as two OXP's try to do the same thing, one gets a conflict and no longer knows which OXP pricing model is in play.''

''For SOTL it's fine, because it uses the scenario system to forcibly eject all other OXP's from use while it's running. But if one wants the OXP to go in the general playing pool set of OXP's, it becomes much more complicated. [[User:Phkb|Phkb]] spent a long time trying to work out why his market script wasn't running, only to find that [[UPS Courier]] was quietly adjusting the markets in certain systems via the planetinfo.plist file. And there are a lot of OXP's that want to play in this space, tweaking prices up or down.''

''Hence one usually abandons using any of the script options, and just tweaks the price after all the scripts have finished playing, ''eg'' in [[Smugglers]]. It was the only way to guarantee getting some sort of bump in a price when wanted.''

== Links ==
*[[Oolite JavaScript Reference: Market Scripts]]
*[[Commodities.plist]] - the precursor (which still mostly works!). If it doesn't see [https://bb.oolite.space/viewtopic.php?p=246145#p246145 here] (2015)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16828 Proposal for 1.82: support for economic changes] ([[User:Cim|Cim]], 2014)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16735 Cim on introducing the Trade-goods.plist and deprecating the commodities.plist] (2014)
{{QuoteText|Text=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.|Source=([https://bb.oolite.space/viewtopic.php?p=226722#p226722 Cim in Progress Thread (2014)])}}
=== Using the Trade-goods.plist ===
*[https://bb.oolite.space/viewtopic.php?f=4&t=20576 How to get the displayName for a commodity in the Main Station Market?] (2020)
*[https://bb.oolite.space/viewtopic.php?f=6&t=17269 Thinking about Planet Income classification] (2015)

{{QuoteText|Text=
In 1.81 this is a lot easier to OXP - you can introduce as many economies as you like, though you are limited to eight economy symbols (so if you wanted lots of economy types, you might end up with Poor Industrial, Avg Industrial and Rich Industrial sharing a symbol on the map). The trade good pricing scripts can then be used to set up different price categories in different economies (and introduce additional trade goods, or split an existing good into multiple categories, which may be necessary if you're adding more economies).

Resetting economies across the planets is a big change in terms of lines of code, but is also very easy to automate. If OXPers are looking for a scripting tool to use for this sort of automation, then NodeJS or io.js is free and also uses Javascript as its language, so you don't need to learn a new one - and may even be able to share code between your build scripts and your OXP, though I haven't tried that yet.|Source=([https://bb.oolite.space/viewtopic.php?f=6&t=17269 Cim in Planet Income thread (2015)])}}

== Preamble ==
To tweak the pricing/availability of commodities in (''eg''.) a station, you need to define the market inside the station's Shipdata.plist - or include a "hook" inside that shipdata.plist to a javascript Oolite Market Script (which allows more complex definitions).

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:

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

== Handlers ==

=== updateGeneralCommodityDefinition ===
{{oolite-method-added|1.81}}
function updateGeneralCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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 = <code>false</code> 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 ===
{{oolite-method-added|1.81}}
function updateLocalCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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.

[https://bb.oolite.space/viewtopic.php?f=4&t=17621#p239979 Here is an example] of how to use this method.

== Links ==

=== Examples ===
*Phkb's update of [[SW_Economy]] (v.3.10) creates new economies for "mining worlds" (hewn out from some low tech poor agricultural worlds) with utterly different price scales for mineral, agricultural & industrial goods, as well as medicine.

''These others will be found at the bottom of the wiki page on the'' [[Trade-goods.plist]].
*Setting an orbital main station's slaves on sale to zero
*Creating an invariant market independent of the local system economy (agricultural/industrial)

Trade-goods (abridged)

2026-06-19T14:48:57Z

Wildeblood: /* comment */

'''You are probably looking for [[Trade-goods.plist]]''', rather than this page.

[[File:Distant Riches.png|thumb|right|200px|MORE THAN FIFTY NEW TRADE GOODS]]

== F.A.Q. ==

The goal of this page is to answer the following questions.

=== How many different places can market influences be hiding? ===

In plists, in market scripts, and in station methods in ''any damned script''.

==== Which plists exactly? ====

At least trade-goods.plist , shipdata.plist , shipdata-overrides.plist , planetinfo.plist can set '''market definitions''' directly.

At least trade-goods.plist , shipdata.plist , shipdata-overrides.plist , planetinfo.plist can set links to '''market scripts'''.

==== Which market scripts exactly? ====

See below.

==== What methods might lurk in ''any damned script''? ====

station.setMarketPrice() or
station.setMarketQuantity()

=== How do we define a new "trade-good" (commodity) '''non-bogusly?''' ===

With trade-goods.plist

=== How will sub-standard OXPs thwart us? ===

By careless use of "default" in market influences to destroy things they don't even know exist.

==== Can we move the world-script in AristoShares OXP into a market script? ====

That would prevent deadbeat scripts from interfering with it. Good idea, research required.

=== Can we define new properties for commodities? ===

Where can we set "aita_image" values?

=== Is the economy 0<->7 dipole set in stone? ===

Does it really require javascript to overcome this?

If so, what is the actual function of the peak_import & peak_export properties?

== Preamble ==

The trade-goods.plist file defines "trade goods" (commodities/cargo). But, it does not ''e.g.'' remove slaves from a particular station or make them cost twice as much as they do at the main orbital station. To do such things, ''i.e.'' to tweak the pricing/availability of commodities in a particular station, you need to define the market inside that station, either within its [[Shipdata.plist]] or within a [[Oolite_Market_Scripts|market script]] linked from its shipdata.plist.

== Overview ==

The '''trade-goods.plist''' file is a dictionary of dictionaries, with (canonical) commodity names as keys to dictionaries of key-value pairs 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 (listed thematically, not alphabetically) ==

=== Display on market screens ===

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

=== market_script ===
The name of a Javascript file to use as a [[Oolite Market Scripts|market script]] for this trade good when calculating main station quantities and prices.

'''Note:''' [https://bb.oolite.space/viewtopic.php?p=235837#p235837 What's the difference between the market script specified in planetinfo.plist and the one called for by trade-goods.plist?] (2015)

=== classes ===
An array of commodity class names. Classes can be used by secondary stations (only secondary markets?) to set pricing rules for groups of commodities.

==== comment ====
A string that will be displayed on the F8 F8 commodity detail screen to describe the commodity. This can be modified later by [[Oolite_JavaScript_Reference:_Manifest#setComment|manifest.setComment()]]

=== 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 [[Oolite_JavaScript_Reference:_Manifest#setShortComment|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.

=== Legality ===

==== 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.

=== Economic biases ===

==== 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.

=== 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.

=== Quantities ===

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

==== 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.''' (Is this true? ''cf.'' Thargoidifier)

==== 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.

=== Discussion of classes ===

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)

== Secondary Market Definitions ==

The primary market is that of the system's main station (''i.e.'' the javascript object system.mainStation.market ) Secondary markets are other markets, which are influenced by the primary market, ''e.g.'' that of a local Rock Hermit, or a visiting liner or another orbital station. Both quantities and prices will be influenced by those of the primary market. Needless to say, the primary market is randomly recalculated each time the system is visited.

Secondary market definitions are entered in the [[shipdata.plist#market_definition|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''':

# The market definition array is searched from top to bottom for the first element matching the trade good
# The market quantity is scaled in proportion to the relative capacities for that good in the two markets.
# 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|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 [[shipdata.plist#market_capacity|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 [[shipdata.plist#market_monitored|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.

=== Links ===
*[https://bb.oolite.space/viewtopic.php?f=2&t=21512 Secondary Market Definitions Defined] (2023)

== 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 for determining markets for new stations.

=== From the vanilla game: Rock Hermits ===
The "market_definition" 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: the Trade-goods.plist updated from the original 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;
};

}
=== A new commodity (from the trade-goods.plist inside "SW Economy") ===
"medicine" = {
"name" = "[commodity-name medicine]";
"classes" = ("oolite-consumer","oolite-medical");
"quantity_unit" = 1;
"peak_export" = 7;
"peak_import" = 0;
"price_average" = 640;
"price_economic" = 0.25;
"price_random" = 0.15;
"quantity_average" = 5;
"quantity_economic" = 1.5;
"quantity_random" = 1.0;
"legality_export" = 0;
"legality_import" = 0;
"trumble_opinion" = 0.50;
"sort_order" = 500;
"comment" = "[oolite-commodity-medicine]";
};

=== Setting an orbital main station's slaves on sale to zero ===
[[User:Phkb|Phkb]] provided this example which requires a ''planetinfo.plist'' & a new ''.js file'' - there are other ways to achieve the same result
==== 1) planetinfo.plist (to invoke the market script) ====
(in the "Config" folder)

{
"0 96" = {market_script = "digebiti_noslaves.js";};
}

==== 2) Market script: digebiti_noslaves.js ====
(in the "Scripts" folder) - note the complex name, which prevents confusion with other snippets of script

"use strict";
this.name = "digebiti_noslaves";
this.author = "Phkb";
this.copyright = "(C) 2022 Phkb";
this.licence = "CC-NC-by-SA 4.0";
this.description = "Removes slaves for sale in Digebiti";
this.version = "1.0";

this.updateLocalCommodityDefinition = function(goodDefinition, station, systemID) {
if (goodDefinition.key == "slaves" && station && station.isMainStation) {
goodDefinition.quantity = 0;
}
return goodDefinition;
}

This method will work, so long as no other OXP changes the market_script property of the Digebiti system in the same way.

=== Creating an invariant market independent of the local system economy (agricultural/industrial) ===
If you just use a market_definition in shipdata.plist for the station, then you're merely setting variations on the primary system market.

If you want the station prices to be independent of (or more loosely tied to) the system it's in, then you need to use a [[Oolite_Market_Scripts|market script]].

So what you'd have is something like this - let's say it's a hydroponics station, so it always sells food and nothing else, regardless of whether the general system economy is industrial or agricultural:

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.key == "food") {
// are we calculating the basic Oolite "food" trade good right now? If yes, set our own static prices
goodDefinition.price = 25; // 2.5 credits
goodDefinition.quantity = 80; // lots of food
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

Now ... the reason that market definitions are preferred to be mutators of the system economy is for two reasons.
1) it means you can avoid the situation where you end up with two adjacent stations with wildly different prices ... but you can of course handle that in other ways too, station positioning, restricted access, ''etc''.
2) it makes it easier to handle OXP trade goods:
- other OXPs might have added more "food" type goods, ''e.g.'' "Meat" or "Cheese"
- you can learn about those and handle them specifically

} else if (goodDefinition.key == "bobsfoodoxp_cheese") {
// set price and quantity here

... but that means a lot of keeping up with what everyone else is doing with custom goods.

The idea was that for your hydroponics station what you might do instead is something like this

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So now if another OXP adds Cheese, provided they declare it as "edible", your station will sell it in high quantities at a big discount, but you don't need to know exactly what the baseline price or quantity was set - so if a food-focused OXP was to add "Wine", "Fine Wine" and "Vintage Wine" at a range of prices and quantities, you'd be automatically handling those in reasonable line with a combination of the Wine OXP's basic pricing structure and your station OXP's "food primary source market" style, without necessarily needing to know about every future Wine OXP there might be and explicitly set compatibility.

Note in this example we're still zeroing out all non-food goods - OXP included! - regardless of the local economy. Maybe at this point we'd want to include and document a "hydroponicsoxp-agriculturalequipment" trade good class that other OXPs could use, which this station would buy up at higher demand and prices than normal.

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else if (goodDefinition.classes.indexOf("hydroponicsoxp-agriculturalequipment") >= 0) {
// custom class for other OXPs to add specific agricultural equipment e.g. combine harvesters, compost, fertiliser
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.capacity = 16; // buy a small amount only // TODO: raise capacity if price per tonne is low
goodDefinition.quantity = 0; // not selling this
} else if (goodDefinition.key == "machinery") {
// the basic Oolite Machinery commodity isn't in the custom class but we need to buy something if
// no OXPs adding it are installed
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.quantity = 0; // not selling
goodDefinition.capacity = 16; // small capacity to buy
} else {
// don't buy or sell any other commodity
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So you can see this one has a mix of using, mutating and overruling the definitions set by the system market and OXP commodity definitions ... with this method you could have a whole bunch of OXPs setting up themed stations, and a whole different bunch adding their own custom commodities, and they'd barely have to know about each other to ensure reasonable consistency and compatibility from someone installing any combination of them. (- by [[User:Cim|Cim]], 2023)

Note: this gives examples for 1 commodity at a time, but not how to easily do that for ALL the commodities on ALL the extra stations in a system.

== Using the trade-goods.plist ==
The trade-goods.plist was designed to make commodities simpler, by:
:1) Making it a dictionary rather than an unlabelled array so one could tell which parameter was which
:2) Making the price range for a trade good dependent on more sensible variables, so rather than setting the price range with a bitmask, one set the price and quantity variations dependent on the economy and on random chance.

Compare the v.1.81 trade-goods.plist with a v.1.80 commodities.plist - they were designed to give near-identical market behaviour for the built-in trade goods.

But - that only made it more comprehensible. It didn't really let one do anything particularly different to Elite 84 markets - mostly including the "Rich Industrial -> Poor Agricultural" single spectrum. One can tweak that a bit with peak_export and peak_import to get slightly different shapes (so a good might peak at Poor Industrial rather than Rich Industrial) but it doesn't really give one the option of a third economy type still.

''So how does one introduce a new economic pole, such as a mining industry?''

For that, one needs the scripting support. [[Oolite JavaScript Reference: Market Scripts]]. 
One can quite literally do whatever one likes with the prices that way. One could have every *system* have its own separate economy, which varied over time according to events, what the player had previously traded, ''etc. etc.'' to produce something comparable to Elite Dangerous' economic sim, if that's the route one wanted to go down. Obviously the more complexity one adds the harder it gets to script up, but it's now all possible.

[[File:SOTL Altmap F8.png|thumb|right|200px|SOTL Altmap F8 commodities market]]
[[SOTL Altmap]] does have an example of it, which basically throws out the original Elite-like algorithm of trade-goods.plist and starts over. It goes *way* beyond just adding a third economy, too.

Basically in SOTL every trade good is tagged in the trade-goods.plist with a bunch of classes
''e.g.''
classes = ("sotl-ex-salvage","sotl-im-refining","sotl-quantity-high","sotl-priceband-3","sotl-demand-medium","sotl-supply-medium","sotl-volatility-low");
So that means:
- exported by salvage economies
- imported by refining economies
- high quantity, moderate price, low price volatility

Then the market script uses those classes, rather than the standard pricing variables, to define the economic behaviour.
:So line 69-74ish: get the current economy description, convert that to the format used in the class name
:...line 85-90: check for the import and export classes for that economy and see if it's imported or exported
:...lines 100-120: apply various special conditions, so e.g. the sotl-ims-radiation class checks the planet surface radiation levels (custom property in sysinfo) and if the radiation level is high, imports these goods even if the basic economy isn't interested (e.g. "sotl-ceramics-ind" in the plist)
:...and then it uses those calculations (and a bunch more of the classes) in the rest of the script to set the price and quantity depending on whether it's an import, an export, or neither

That's massive overkill for just adding a third mining economy, but one would need to work on a similar principle.

:1) Tag every commodity with classes for (import|export|none)-(agricultural|industrial|mining) as appropriate
:2) Adjust the economy names (there are a few different ways one could do that) so that the 8 economy IDs were allocated to agricultural, industrial and mining economies
:3) Have a price script which like the SOTL one gets the current economy, looks at the classes list to find out if the commodity is imported or exported or neither, and sets the price and quantity accordingly. One could use the standard price_economic, price_average, price_random properties in the plist to give baseline data to the script if one was not planning to do anything too weird.

{Technically one doesn't need the classes - just have the price script contain a list of goods internally for each economy - but this way if other people add extra trade goods in their own OXPs, they can tag them up for mining economy support too}

All fairly straightforward theoretically.

''The biggest impediment to doing a wholesale reworking of the economic system, is just how incompatible it makes lots and lots of OXP's. In order to override the vanilla commodities as in SOTL, requires setting a script for each in trade-goods.plist. Which is fine if it's the only OXP that wants to play around with commodity prices. As soon as two OXP's try to do the same thing, one gets a conflict and no longer knows which OXP pricing model is in play.''

''For SOTL it's fine, because it uses the scenario system to forcibly eject all other OXP's from use while it's running. But if one wants the OXP to go in the general playing pool set of OXP's, it becomes much more complicated. [[User:Phkb|Phkb]] spent a long time trying to work out why his market script wasn't running, only to find that [[UPS Courier]] was quietly adjusting the markets in certain systems via the planetinfo.plist file. And there are a lot of OXP's that want to play in this space, tweaking prices up or down.''

''Hence one usually abandons using any of the script options, and just tweaks the price after all the scripts have finished playing, ''eg'' in [[Smugglers]]. It was the only way to guarantee getting some sort of bump in a price when wanted.''

== Links ==
*[[Oolite JavaScript Reference: Market Scripts]]
*[[Commodities.plist]] - the precursor (which still mostly works!). If it doesn't see [https://bb.oolite.space/viewtopic.php?p=246145#p246145 here] (2015)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16828 Proposal for 1.82: support for economic changes] ([[User:Cim|Cim]], 2014)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16735 Cim on introducing the Trade-goods.plist and deprecating the commodities.plist] (2014)
{{QuoteText|Text=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.|Source=([https://bb.oolite.space/viewtopic.php?p=226722#p226722 Cim in Progress Thread (2014)])}}
=== Using the Trade-goods.plist ===
*[https://bb.oolite.space/viewtopic.php?f=4&t=20576 How to get the displayName for a commodity in the Main Station Market?] (2020)
*[https://bb.oolite.space/viewtopic.php?f=6&t=17269 Thinking about Planet Income classification] (2015)

{{QuoteText|Text=
In 1.81 this is a lot easier to OXP - you can introduce as many economies as you like, though you are limited to eight economy symbols (so if you wanted lots of economy types, you might end up with Poor Industrial, Avg Industrial and Rich Industrial sharing a symbol on the map). The trade good pricing scripts can then be used to set up different price categories in different economies (and introduce additional trade goods, or split an existing good into multiple categories, which may be necessary if you're adding more economies).

Resetting economies across the planets is a big change in terms of lines of code, but is also very easy to automate. If OXPers are looking for a scripting tool to use for this sort of automation, then NodeJS or io.js is free and also uses Javascript as its language, so you don't need to learn a new one - and may even be able to share code between your build scripts and your OXP, though I haven't tried that yet.|Source=([https://bb.oolite.space/viewtopic.php?f=6&t=17269 Cim in Planet Income thread (2015)])}}

== Preamble ==
To tweak the pricing/availability of commodities in (''eg''.) a station, you need to define the market inside the station's Shipdata.plist - or include a "hook" inside that shipdata.plist to a javascript Oolite Market Script (which allows more complex definitions).

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:

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

== Handlers ==

=== updateGeneralCommodityDefinition ===
{{oolite-method-added|1.81}}
function updateGeneralCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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 = <code>false</code> 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 ===
{{oolite-method-added|1.81}}
function updateLocalCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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.

[https://bb.oolite.space/viewtopic.php?f=4&t=17621#p239979 Here is an example] of how to use this method.

== Links ==

=== Examples ===
*Phkb's update of [[SW_Economy]] (v.3.10) creates new economies for "mining worlds" (hewn out from some low tech poor agricultural worlds) with utterly different price scales for mineral, agricultural & industrial goods, as well as medicine.

''These others will be found at the bottom of the wiki page on the'' [[Trade-goods.plist]].
*Setting an orbital main station's slaves on sale to zero
*Creating an invariant market independent of the local system economy (agricultural/industrial)

Trade-goods (abridged)

2026-06-19T14:48:05Z

Wildeblood: /* name */

'''You are probably looking for [[Trade-goods.plist]]''', rather than this page.

[[File:Distant Riches.png|thumb|right|200px|MORE THAN FIFTY NEW TRADE GOODS]]

== F.A.Q. ==

The goal of this page is to answer the following questions.

=== How many different places can market influences be hiding? ===

In plists, in market scripts, and in station methods in ''any damned script''.

==== Which plists exactly? ====

At least trade-goods.plist , shipdata.plist , shipdata-overrides.plist , planetinfo.plist can set '''market definitions''' directly.

At least trade-goods.plist , shipdata.plist , shipdata-overrides.plist , planetinfo.plist can set links to '''market scripts'''.

==== Which market scripts exactly? ====

See below.

==== What methods might lurk in ''any damned script''? ====

station.setMarketPrice() or
station.setMarketQuantity()

=== How do we define a new "trade-good" (commodity) '''non-bogusly?''' ===

With trade-goods.plist

=== How will sub-standard OXPs thwart us? ===

By careless use of "default" in market influences to destroy things they don't even know exist.

==== Can we move the world-script in AristoShares OXP into a market script? ====

That would prevent deadbeat scripts from interfering with it. Good idea, research required.

=== Can we define new properties for commodities? ===

Where can we set "aita_image" values?

=== Is the economy 0<->7 dipole set in stone? ===

Does it really require javascript to overcome this?

If so, what is the actual function of the peak_import & peak_export properties?

== Preamble ==

The trade-goods.plist file defines "trade goods" (commodities/cargo). But, it does not ''e.g.'' remove slaves from a particular station or make them cost twice as much as they do at the main orbital station. To do such things, ''i.e.'' to tweak the pricing/availability of commodities in a particular station, you need to define the market inside that station, either within its [[Shipdata.plist]] or within a [[Oolite_Market_Scripts|market script]] linked from its shipdata.plist.

== Overview ==

The '''trade-goods.plist''' file is a dictionary of dictionaries, with (canonical) commodity names as keys to dictionaries of key-value pairs 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 (listed thematically, not alphabetically) ==

=== Display on market screens ===

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

=== market_script ===
The name of a Javascript file to use as a [[Oolite Market Scripts|market script]] for this trade good when calculating main station quantities and prices.

'''Note:''' [https://bb.oolite.space/viewtopic.php?p=235837#p235837 What's the difference between the market script specified in planetinfo.plist and the one called for by trade-goods.plist?] (2015)

=== classes ===
An array of commodity class names. Classes can be used by secondary stations (only secondary markets?) to set pricing rules for groups of commodities.

=== comment ===
A string that will be displayed on the F8 F8 commodity detail screen to describe the commodity. This can be modified later by [[Oolite_JavaScript_Reference:_Manifest#setComment|manifest.setComment()]]

=== 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 [[Oolite_JavaScript_Reference:_Manifest#setShortComment|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.

=== Legality ===

==== 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.

=== Economic biases ===

==== 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.

=== 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.

=== Quantities ===

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

==== 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.''' (Is this true? ''cf.'' Thargoidifier)

==== 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.

=== Discussion of classes ===

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)

== Secondary Market Definitions ==

The primary market is that of the system's main station (''i.e.'' the javascript object system.mainStation.market ) Secondary markets are other markets, which are influenced by the primary market, ''e.g.'' that of a local Rock Hermit, or a visiting liner or another orbital station. Both quantities and prices will be influenced by those of the primary market. Needless to say, the primary market is randomly recalculated each time the system is visited.

Secondary market definitions are entered in the [[shipdata.plist#market_definition|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''':

# The market definition array is searched from top to bottom for the first element matching the trade good
# The market quantity is scaled in proportion to the relative capacities for that good in the two markets.
# 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|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 [[shipdata.plist#market_capacity|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 [[shipdata.plist#market_monitored|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.

=== Links ===
*[https://bb.oolite.space/viewtopic.php?f=2&t=21512 Secondary Market Definitions Defined] (2023)

== 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 for determining markets for new stations.

=== From the vanilla game: Rock Hermits ===
The "market_definition" 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: the Trade-goods.plist updated from the original 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;
};

}
=== A new commodity (from the trade-goods.plist inside "SW Economy") ===
"medicine" = {
"name" = "[commodity-name medicine]";
"classes" = ("oolite-consumer","oolite-medical");
"quantity_unit" = 1;
"peak_export" = 7;
"peak_import" = 0;
"price_average" = 640;
"price_economic" = 0.25;
"price_random" = 0.15;
"quantity_average" = 5;
"quantity_economic" = 1.5;
"quantity_random" = 1.0;
"legality_export" = 0;
"legality_import" = 0;
"trumble_opinion" = 0.50;
"sort_order" = 500;
"comment" = "[oolite-commodity-medicine]";
};

=== Setting an orbital main station's slaves on sale to zero ===
[[User:Phkb|Phkb]] provided this example which requires a ''planetinfo.plist'' & a new ''.js file'' - there are other ways to achieve the same result
==== 1) planetinfo.plist (to invoke the market script) ====
(in the "Config" folder)

{
"0 96" = {market_script = "digebiti_noslaves.js";};
}

==== 2) Market script: digebiti_noslaves.js ====
(in the "Scripts" folder) - note the complex name, which prevents confusion with other snippets of script

"use strict";
this.name = "digebiti_noslaves";
this.author = "Phkb";
this.copyright = "(C) 2022 Phkb";
this.licence = "CC-NC-by-SA 4.0";
this.description = "Removes slaves for sale in Digebiti";
this.version = "1.0";

this.updateLocalCommodityDefinition = function(goodDefinition, station, systemID) {
if (goodDefinition.key == "slaves" && station && station.isMainStation) {
goodDefinition.quantity = 0;
}
return goodDefinition;
}

This method will work, so long as no other OXP changes the market_script property of the Digebiti system in the same way.

=== Creating an invariant market independent of the local system economy (agricultural/industrial) ===
If you just use a market_definition in shipdata.plist for the station, then you're merely setting variations on the primary system market.

If you want the station prices to be independent of (or more loosely tied to) the system it's in, then you need to use a [[Oolite_Market_Scripts|market script]].

So what you'd have is something like this - let's say it's a hydroponics station, so it always sells food and nothing else, regardless of whether the general system economy is industrial or agricultural:

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.key == "food") {
// are we calculating the basic Oolite "food" trade good right now? If yes, set our own static prices
goodDefinition.price = 25; // 2.5 credits
goodDefinition.quantity = 80; // lots of food
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

Now ... the reason that market definitions are preferred to be mutators of the system economy is for two reasons.
1) it means you can avoid the situation where you end up with two adjacent stations with wildly different prices ... but you can of course handle that in other ways too, station positioning, restricted access, ''etc''.
2) it makes it easier to handle OXP trade goods:
- other OXPs might have added more "food" type goods, ''e.g.'' "Meat" or "Cheese"
- you can learn about those and handle them specifically

} else if (goodDefinition.key == "bobsfoodoxp_cheese") {
// set price and quantity here

... but that means a lot of keeping up with what everyone else is doing with custom goods.

The idea was that for your hydroponics station what you might do instead is something like this

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So now if another OXP adds Cheese, provided they declare it as "edible", your station will sell it in high quantities at a big discount, but you don't need to know exactly what the baseline price or quantity was set - so if a food-focused OXP was to add "Wine", "Fine Wine" and "Vintage Wine" at a range of prices and quantities, you'd be automatically handling those in reasonable line with a combination of the Wine OXP's basic pricing structure and your station OXP's "food primary source market" style, without necessarily needing to know about every future Wine OXP there might be and explicitly set compatibility.

Note in this example we're still zeroing out all non-food goods - OXP included! - regardless of the local economy. Maybe at this point we'd want to include and document a "hydroponicsoxp-agriculturalequipment" trade good class that other OXPs could use, which this station would buy up at higher demand and prices than normal.

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else if (goodDefinition.classes.indexOf("hydroponicsoxp-agriculturalequipment") >= 0) {
// custom class for other OXPs to add specific agricultural equipment e.g. combine harvesters, compost, fertiliser
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.capacity = 16; // buy a small amount only // TODO: raise capacity if price per tonne is low
goodDefinition.quantity = 0; // not selling this
} else if (goodDefinition.key == "machinery") {
// the basic Oolite Machinery commodity isn't in the custom class but we need to buy something if
// no OXPs adding it are installed
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.quantity = 0; // not selling
goodDefinition.capacity = 16; // small capacity to buy
} else {
// don't buy or sell any other commodity
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So you can see this one has a mix of using, mutating and overruling the definitions set by the system market and OXP commodity definitions ... with this method you could have a whole bunch of OXPs setting up themed stations, and a whole different bunch adding their own custom commodities, and they'd barely have to know about each other to ensure reasonable consistency and compatibility from someone installing any combination of them. (- by [[User:Cim|Cim]], 2023)

Note: this gives examples for 1 commodity at a time, but not how to easily do that for ALL the commodities on ALL the extra stations in a system.

== Using the trade-goods.plist ==
The trade-goods.plist was designed to make commodities simpler, by:
:1) Making it a dictionary rather than an unlabelled array so one could tell which parameter was which
:2) Making the price range for a trade good dependent on more sensible variables, so rather than setting the price range with a bitmask, one set the price and quantity variations dependent on the economy and on random chance.

Compare the v.1.81 trade-goods.plist with a v.1.80 commodities.plist - they were designed to give near-identical market behaviour for the built-in trade goods.

But - that only made it more comprehensible. It didn't really let one do anything particularly different to Elite 84 markets - mostly including the "Rich Industrial -> Poor Agricultural" single spectrum. One can tweak that a bit with peak_export and peak_import to get slightly different shapes (so a good might peak at Poor Industrial rather than Rich Industrial) but it doesn't really give one the option of a third economy type still.

''So how does one introduce a new economic pole, such as a mining industry?''

For that, one needs the scripting support. [[Oolite JavaScript Reference: Market Scripts]]. 
One can quite literally do whatever one likes with the prices that way. One could have every *system* have its own separate economy, which varied over time according to events, what the player had previously traded, ''etc. etc.'' to produce something comparable to Elite Dangerous' economic sim, if that's the route one wanted to go down. Obviously the more complexity one adds the harder it gets to script up, but it's now all possible.

[[File:SOTL Altmap F8.png|thumb|right|200px|SOTL Altmap F8 commodities market]]
[[SOTL Altmap]] does have an example of it, which basically throws out the original Elite-like algorithm of trade-goods.plist and starts over. It goes *way* beyond just adding a third economy, too.

Basically in SOTL every trade good is tagged in the trade-goods.plist with a bunch of classes
''e.g.''
classes = ("sotl-ex-salvage","sotl-im-refining","sotl-quantity-high","sotl-priceband-3","sotl-demand-medium","sotl-supply-medium","sotl-volatility-low");
So that means:
- exported by salvage economies
- imported by refining economies
- high quantity, moderate price, low price volatility

Then the market script uses those classes, rather than the standard pricing variables, to define the economic behaviour.
:So line 69-74ish: get the current economy description, convert that to the format used in the class name
:...line 85-90: check for the import and export classes for that economy and see if it's imported or exported
:...lines 100-120: apply various special conditions, so e.g. the sotl-ims-radiation class checks the planet surface radiation levels (custom property in sysinfo) and if the radiation level is high, imports these goods even if the basic economy isn't interested (e.g. "sotl-ceramics-ind" in the plist)
:...and then it uses those calculations (and a bunch more of the classes) in the rest of the script to set the price and quantity depending on whether it's an import, an export, or neither

That's massive overkill for just adding a third mining economy, but one would need to work on a similar principle.

:1) Tag every commodity with classes for (import|export|none)-(agricultural|industrial|mining) as appropriate
:2) Adjust the economy names (there are a few different ways one could do that) so that the 8 economy IDs were allocated to agricultural, industrial and mining economies
:3) Have a price script which like the SOTL one gets the current economy, looks at the classes list to find out if the commodity is imported or exported or neither, and sets the price and quantity accordingly. One could use the standard price_economic, price_average, price_random properties in the plist to give baseline data to the script if one was not planning to do anything too weird.

{Technically one doesn't need the classes - just have the price script contain a list of goods internally for each economy - but this way if other people add extra trade goods in their own OXPs, they can tag them up for mining economy support too}

All fairly straightforward theoretically.

''The biggest impediment to doing a wholesale reworking of the economic system, is just how incompatible it makes lots and lots of OXP's. In order to override the vanilla commodities as in SOTL, requires setting a script for each in trade-goods.plist. Which is fine if it's the only OXP that wants to play around with commodity prices. As soon as two OXP's try to do the same thing, one gets a conflict and no longer knows which OXP pricing model is in play.''

''For SOTL it's fine, because it uses the scenario system to forcibly eject all other OXP's from use while it's running. But if one wants the OXP to go in the general playing pool set of OXP's, it becomes much more complicated. [[User:Phkb|Phkb]] spent a long time trying to work out why his market script wasn't running, only to find that [[UPS Courier]] was quietly adjusting the markets in certain systems via the planetinfo.plist file. And there are a lot of OXP's that want to play in this space, tweaking prices up or down.''

''Hence one usually abandons using any of the script options, and just tweaks the price after all the scripts have finished playing, ''eg'' in [[Smugglers]]. It was the only way to guarantee getting some sort of bump in a price when wanted.''

== Links ==
*[[Oolite JavaScript Reference: Market Scripts]]
*[[Commodities.plist]] - the precursor (which still mostly works!). If it doesn't see [https://bb.oolite.space/viewtopic.php?p=246145#p246145 here] (2015)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16828 Proposal for 1.82: support for economic changes] ([[User:Cim|Cim]], 2014)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16735 Cim on introducing the Trade-goods.plist and deprecating the commodities.plist] (2014)
{{QuoteText|Text=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.|Source=([https://bb.oolite.space/viewtopic.php?p=226722#p226722 Cim in Progress Thread (2014)])}}
=== Using the Trade-goods.plist ===
*[https://bb.oolite.space/viewtopic.php?f=4&t=20576 How to get the displayName for a commodity in the Main Station Market?] (2020)
*[https://bb.oolite.space/viewtopic.php?f=6&t=17269 Thinking about Planet Income classification] (2015)

{{QuoteText|Text=
In 1.81 this is a lot easier to OXP - you can introduce as many economies as you like, though you are limited to eight economy symbols (so if you wanted lots of economy types, you might end up with Poor Industrial, Avg Industrial and Rich Industrial sharing a symbol on the map). The trade good pricing scripts can then be used to set up different price categories in different economies (and introduce additional trade goods, or split an existing good into multiple categories, which may be necessary if you're adding more economies).

Resetting economies across the planets is a big change in terms of lines of code, but is also very easy to automate. If OXPers are looking for a scripting tool to use for this sort of automation, then NodeJS or io.js is free and also uses Javascript as its language, so you don't need to learn a new one - and may even be able to share code between your build scripts and your OXP, though I haven't tried that yet.|Source=([https://bb.oolite.space/viewtopic.php?f=6&t=17269 Cim in Planet Income thread (2015)])}}

== Preamble ==
To tweak the pricing/availability of commodities in (''eg''.) a station, you need to define the market inside the station's Shipdata.plist - or include a "hook" inside that shipdata.plist to a javascript Oolite Market Script (which allows more complex definitions).

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:

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

== Handlers ==

=== updateGeneralCommodityDefinition ===
{{oolite-method-added|1.81}}
function updateGeneralCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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 = <code>false</code> 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 ===
{{oolite-method-added|1.81}}
function updateLocalCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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.

[https://bb.oolite.space/viewtopic.php?f=4&t=17621#p239979 Here is an example] of how to use this method.

== Links ==

=== Examples ===
*Phkb's update of [[SW_Economy]] (v.3.10) creates new economies for "mining worlds" (hewn out from some low tech poor agricultural worlds) with utterly different price scales for mineral, agricultural & industrial goods, as well as medicine.

''These others will be found at the bottom of the wiki page on the'' [[Trade-goods.plist]].
*Setting an orbital main station's slaves on sale to zero
*Creating an invariant market independent of the local system economy (agricultural/industrial)

Trade-goods (abridged)

2026-06-19T14:20:13Z

Wildeblood: /* quantity_average */

'''You are probably looking for [[Trade-goods.plist]]''', rather than this page.

[[File:Distant Riches.png|thumb|right|200px|MORE THAN FIFTY NEW TRADE GOODS]]

== F.A.Q. ==

The goal of this page is to answer the following questions.

=== How many different places can market influences be hiding? ===

In plists, in market scripts, and in station methods in ''any damned script''.

==== Which plists exactly? ====

At least trade-goods.plist , shipdata.plist , shipdata-overrides.plist , planetinfo.plist can set '''market definitions''' directly.

At least trade-goods.plist , shipdata.plist , shipdata-overrides.plist , planetinfo.plist can set links to '''market scripts'''.

==== Which market scripts exactly? ====

See below.

==== What methods might lurk in ''any damned script''? ====

station.setMarketPrice() or
station.setMarketQuantity()

=== How do we define a new "trade-good" (commodity) '''non-bogusly?''' ===

With trade-goods.plist

=== How will sub-standard OXPs thwart us? ===

By careless use of "default" in market influences to destroy things they don't even know exist.

==== Can we move the world-script in AristoShares OXP into a market script? ====

That would prevent deadbeat scripts from interfering with it. Good idea, research required.

=== Can we define new properties for commodities? ===

Where can we set "aita_image" values?

=== Is the economy 0<->7 dipole set in stone? ===

Does it really require javascript to overcome this?

If so, what is the actual function of the peak_import & peak_export properties?

== Preamble ==

The trade-goods.plist file defines "trade goods" (commodities/cargo). But, it does not ''e.g.'' remove slaves from a particular station or make them cost twice as much as they do at the main orbital station. To do such things, ''i.e.'' to tweak the pricing/availability of commodities in a particular station, you need to define the market inside that station, either within its [[Shipdata.plist]] or within a [[Oolite_Market_Scripts|market script]] linked from its shipdata.plist.

== Overview ==

The '''trade-goods.plist''' file is a dictionary of dictionaries, with (canonical) commodity names as keys to dictionaries of key-value pairs 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 (listed thematically, not alphabetically) ==

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

=== market_script ===
The name of a Javascript file to use as a [[Oolite Market Scripts|market script]] for this trade good when calculating main station quantities and prices.

'''Note:''' [https://bb.oolite.space/viewtopic.php?p=235837#p235837 What's the difference between the market script specified in planetinfo.plist and the one called for by trade-goods.plist?] (2015)

=== classes ===
An array of commodity class names. Classes can be used by secondary stations (only secondary markets?) to set pricing rules for groups of commodities.

=== comment ===
A string that will be displayed on the F8 F8 commodity detail screen to describe the commodity. This can be modified later by [[Oolite_JavaScript_Reference:_Manifest#setComment|manifest.setComment()]]

=== 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 [[Oolite_JavaScript_Reference:_Manifest#setShortComment|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.

=== Legality ===

==== 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.

=== Economic biases ===

==== 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.

=== 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.

=== Quantities ===

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

==== 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.''' (Is this true? ''cf.'' Thargoidifier)

==== 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.

=== Discussion of classes ===

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)

== Secondary Market Definitions ==

The primary market is that of the system's main station (''i.e.'' the javascript object system.mainStation.market ) Secondary markets are other markets, which are influenced by the primary market, ''e.g.'' that of a local Rock Hermit, or a visiting liner or another orbital station. Both quantities and prices will be influenced by those of the primary market. Needless to say, the primary market is randomly recalculated each time the system is visited.

Secondary market definitions are entered in the [[shipdata.plist#market_definition|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''':

# The market definition array is searched from top to bottom for the first element matching the trade good
# The market quantity is scaled in proportion to the relative capacities for that good in the two markets.
# 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|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 [[shipdata.plist#market_capacity|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 [[shipdata.plist#market_monitored|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.

=== Links ===
*[https://bb.oolite.space/viewtopic.php?f=2&t=21512 Secondary Market Definitions Defined] (2023)

== 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 for determining markets for new stations.

=== From the vanilla game: Rock Hermits ===
The "market_definition" 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: the Trade-goods.plist updated from the original 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;
};

}
=== A new commodity (from the trade-goods.plist inside "SW Economy") ===
"medicine" = {
"name" = "[commodity-name medicine]";
"classes" = ("oolite-consumer","oolite-medical");
"quantity_unit" = 1;
"peak_export" = 7;
"peak_import" = 0;
"price_average" = 640;
"price_economic" = 0.25;
"price_random" = 0.15;
"quantity_average" = 5;
"quantity_economic" = 1.5;
"quantity_random" = 1.0;
"legality_export" = 0;
"legality_import" = 0;
"trumble_opinion" = 0.50;
"sort_order" = 500;
"comment" = "[oolite-commodity-medicine]";
};

=== Setting an orbital main station's slaves on sale to zero ===
[[User:Phkb|Phkb]] provided this example which requires a ''planetinfo.plist'' & a new ''.js file'' - there are other ways to achieve the same result
==== 1) planetinfo.plist (to invoke the market script) ====
(in the "Config" folder)

{
"0 96" = {market_script = "digebiti_noslaves.js";};
}

==== 2) Market script: digebiti_noslaves.js ====
(in the "Scripts" folder) - note the complex name, which prevents confusion with other snippets of script

"use strict";
this.name = "digebiti_noslaves";
this.author = "Phkb";
this.copyright = "(C) 2022 Phkb";
this.licence = "CC-NC-by-SA 4.0";
this.description = "Removes slaves for sale in Digebiti";
this.version = "1.0";

this.updateLocalCommodityDefinition = function(goodDefinition, station, systemID) {
if (goodDefinition.key == "slaves" && station && station.isMainStation) {
goodDefinition.quantity = 0;
}
return goodDefinition;
}

This method will work, so long as no other OXP changes the market_script property of the Digebiti system in the same way.

=== Creating an invariant market independent of the local system economy (agricultural/industrial) ===
If you just use a market_definition in shipdata.plist for the station, then you're merely setting variations on the primary system market.

If you want the station prices to be independent of (or more loosely tied to) the system it's in, then you need to use a [[Oolite_Market_Scripts|market script]].

So what you'd have is something like this - let's say it's a hydroponics station, so it always sells food and nothing else, regardless of whether the general system economy is industrial or agricultural:

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.key == "food") {
// are we calculating the basic Oolite "food" trade good right now? If yes, set our own static prices
goodDefinition.price = 25; // 2.5 credits
goodDefinition.quantity = 80; // lots of food
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

Now ... the reason that market definitions are preferred to be mutators of the system economy is for two reasons.
1) it means you can avoid the situation where you end up with two adjacent stations with wildly different prices ... but you can of course handle that in other ways too, station positioning, restricted access, ''etc''.
2) it makes it easier to handle OXP trade goods:
- other OXPs might have added more "food" type goods, ''e.g.'' "Meat" or "Cheese"
- you can learn about those and handle them specifically

} else if (goodDefinition.key == "bobsfoodoxp_cheese") {
// set price and quantity here

... but that means a lot of keeping up with what everyone else is doing with custom goods.

The idea was that for your hydroponics station what you might do instead is something like this

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So now if another OXP adds Cheese, provided they declare it as "edible", your station will sell it in high quantities at a big discount, but you don't need to know exactly what the baseline price or quantity was set - so if a food-focused OXP was to add "Wine", "Fine Wine" and "Vintage Wine" at a range of prices and quantities, you'd be automatically handling those in reasonable line with a combination of the Wine OXP's basic pricing structure and your station OXP's "food primary source market" style, without necessarily needing to know about every future Wine OXP there might be and explicitly set compatibility.

Note in this example we're still zeroing out all non-food goods - OXP included! - regardless of the local economy. Maybe at this point we'd want to include and document a "hydroponicsoxp-agriculturalequipment" trade good class that other OXPs could use, which this station would buy up at higher demand and prices than normal.

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else if (goodDefinition.classes.indexOf("hydroponicsoxp-agriculturalequipment") >= 0) {
// custom class for other OXPs to add specific agricultural equipment e.g. combine harvesters, compost, fertiliser
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.capacity = 16; // buy a small amount only // TODO: raise capacity if price per tonne is low
goodDefinition.quantity = 0; // not selling this
} else if (goodDefinition.key == "machinery") {
// the basic Oolite Machinery commodity isn't in the custom class but we need to buy something if
// no OXPs adding it are installed
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.quantity = 0; // not selling
goodDefinition.capacity = 16; // small capacity to buy
} else {
// don't buy or sell any other commodity
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So you can see this one has a mix of using, mutating and overruling the definitions set by the system market and OXP commodity definitions ... with this method you could have a whole bunch of OXPs setting up themed stations, and a whole different bunch adding their own custom commodities, and they'd barely have to know about each other to ensure reasonable consistency and compatibility from someone installing any combination of them. (- by [[User:Cim|Cim]], 2023)

Note: this gives examples for 1 commodity at a time, but not how to easily do that for ALL the commodities on ALL the extra stations in a system.

== Using the trade-goods.plist ==
The trade-goods.plist was designed to make commodities simpler, by:
:1) Making it a dictionary rather than an unlabelled array so one could tell which parameter was which
:2) Making the price range for a trade good dependent on more sensible variables, so rather than setting the price range with a bitmask, one set the price and quantity variations dependent on the economy and on random chance.

Compare the v.1.81 trade-goods.plist with a v.1.80 commodities.plist - they were designed to give near-identical market behaviour for the built-in trade goods.

But - that only made it more comprehensible. It didn't really let one do anything particularly different to Elite 84 markets - mostly including the "Rich Industrial -> Poor Agricultural" single spectrum. One can tweak that a bit with peak_export and peak_import to get slightly different shapes (so a good might peak at Poor Industrial rather than Rich Industrial) but it doesn't really give one the option of a third economy type still.

''So how does one introduce a new economic pole, such as a mining industry?''

For that, one needs the scripting support. [[Oolite JavaScript Reference: Market Scripts]]. 
One can quite literally do whatever one likes with the prices that way. One could have every *system* have its own separate economy, which varied over time according to events, what the player had previously traded, ''etc. etc.'' to produce something comparable to Elite Dangerous' economic sim, if that's the route one wanted to go down. Obviously the more complexity one adds the harder it gets to script up, but it's now all possible.

[[File:SOTL Altmap F8.png|thumb|right|200px|SOTL Altmap F8 commodities market]]
[[SOTL Altmap]] does have an example of it, which basically throws out the original Elite-like algorithm of trade-goods.plist and starts over. It goes *way* beyond just adding a third economy, too.

Basically in SOTL every trade good is tagged in the trade-goods.plist with a bunch of classes
''e.g.''
classes = ("sotl-ex-salvage","sotl-im-refining","sotl-quantity-high","sotl-priceband-3","sotl-demand-medium","sotl-supply-medium","sotl-volatility-low");
So that means:
- exported by salvage economies
- imported by refining economies
- high quantity, moderate price, low price volatility

Then the market script uses those classes, rather than the standard pricing variables, to define the economic behaviour.
:So line 69-74ish: get the current economy description, convert that to the format used in the class name
:...line 85-90: check for the import and export classes for that economy and see if it's imported or exported
:...lines 100-120: apply various special conditions, so e.g. the sotl-ims-radiation class checks the planet surface radiation levels (custom property in sysinfo) and if the radiation level is high, imports these goods even if the basic economy isn't interested (e.g. "sotl-ceramics-ind" in the plist)
:...and then it uses those calculations (and a bunch more of the classes) in the rest of the script to set the price and quantity depending on whether it's an import, an export, or neither

That's massive overkill for just adding a third mining economy, but one would need to work on a similar principle.

:1) Tag every commodity with classes for (import|export|none)-(agricultural|industrial|mining) as appropriate
:2) Adjust the economy names (there are a few different ways one could do that) so that the 8 economy IDs were allocated to agricultural, industrial and mining economies
:3) Have a price script which like the SOTL one gets the current economy, looks at the classes list to find out if the commodity is imported or exported or neither, and sets the price and quantity accordingly. One could use the standard price_economic, price_average, price_random properties in the plist to give baseline data to the script if one was not planning to do anything too weird.

{Technically one doesn't need the classes - just have the price script contain a list of goods internally for each economy - but this way if other people add extra trade goods in their own OXPs, they can tag them up for mining economy support too}

All fairly straightforward theoretically.

''The biggest impediment to doing a wholesale reworking of the economic system, is just how incompatible it makes lots and lots of OXP's. In order to override the vanilla commodities as in SOTL, requires setting a script for each in trade-goods.plist. Which is fine if it's the only OXP that wants to play around with commodity prices. As soon as two OXP's try to do the same thing, one gets a conflict and no longer knows which OXP pricing model is in play.''

''For SOTL it's fine, because it uses the scenario system to forcibly eject all other OXP's from use while it's running. But if one wants the OXP to go in the general playing pool set of OXP's, it becomes much more complicated. [[User:Phkb|Phkb]] spent a long time trying to work out why his market script wasn't running, only to find that [[UPS Courier]] was quietly adjusting the markets in certain systems via the planetinfo.plist file. And there are a lot of OXP's that want to play in this space, tweaking prices up or down.''

''Hence one usually abandons using any of the script options, and just tweaks the price after all the scripts have finished playing, ''eg'' in [[Smugglers]]. It was the only way to guarantee getting some sort of bump in a price when wanted.''

== Links ==
*[[Oolite JavaScript Reference: Market Scripts]]
*[[Commodities.plist]] - the precursor (which still mostly works!). If it doesn't see [https://bb.oolite.space/viewtopic.php?p=246145#p246145 here] (2015)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16828 Proposal for 1.82: support for economic changes] ([[User:Cim|Cim]], 2014)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16735 Cim on introducing the Trade-goods.plist and deprecating the commodities.plist] (2014)
{{QuoteText|Text=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.|Source=([https://bb.oolite.space/viewtopic.php?p=226722#p226722 Cim in Progress Thread (2014)])}}
=== Using the Trade-goods.plist ===
*[https://bb.oolite.space/viewtopic.php?f=4&t=20576 How to get the displayName for a commodity in the Main Station Market?] (2020)
*[https://bb.oolite.space/viewtopic.php?f=6&t=17269 Thinking about Planet Income classification] (2015)

{{QuoteText|Text=
In 1.81 this is a lot easier to OXP - you can introduce as many economies as you like, though you are limited to eight economy symbols (so if you wanted lots of economy types, you might end up with Poor Industrial, Avg Industrial and Rich Industrial sharing a symbol on the map). The trade good pricing scripts can then be used to set up different price categories in different economies (and introduce additional trade goods, or split an existing good into multiple categories, which may be necessary if you're adding more economies).

Resetting economies across the planets is a big change in terms of lines of code, but is also very easy to automate. If OXPers are looking for a scripting tool to use for this sort of automation, then NodeJS or io.js is free and also uses Javascript as its language, so you don't need to learn a new one - and may even be able to share code between your build scripts and your OXP, though I haven't tried that yet.|Source=([https://bb.oolite.space/viewtopic.php?f=6&t=17269 Cim in Planet Income thread (2015)])}}

== Preamble ==
To tweak the pricing/availability of commodities in (''eg''.) a station, you need to define the market inside the station's Shipdata.plist - or include a "hook" inside that shipdata.plist to a javascript Oolite Market Script (which allows more complex definitions).

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:

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

== Handlers ==

=== updateGeneralCommodityDefinition ===
{{oolite-method-added|1.81}}
function updateGeneralCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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 = <code>false</code> 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 ===
{{oolite-method-added|1.81}}
function updateLocalCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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.

[https://bb.oolite.space/viewtopic.php?f=4&t=17621#p239979 Here is an example] of how to use this method.

== Links ==

=== Examples ===
*Phkb's update of [[SW_Economy]] (v.3.10) creates new economies for "mining worlds" (hewn out from some low tech poor agricultural worlds) with utterly different price scales for mineral, agricultural & industrial goods, as well as medicine.

''These others will be found at the bottom of the wiki page on the'' [[Trade-goods.plist]].
*Setting an orbital main station's slaves on sale to zero
*Creating an invariant market independent of the local system economy (agricultural/industrial)

Trade-goods (abridged)

2026-06-19T14:17:55Z

Wildeblood: /* capacity */

'''You are probably looking for [[Trade-goods.plist]]''', rather than this page.

[[File:Distant Riches.png|thumb|right|200px|MORE THAN FIFTY NEW TRADE GOODS]]

== F.A.Q. ==

The goal of this page is to answer the following questions.

=== How many different places can market influences be hiding? ===

In plists, in market scripts, and in station methods in ''any damned script''.

==== Which plists exactly? ====

At least trade-goods.plist , shipdata.plist , shipdata-overrides.plist , planetinfo.plist can set '''market definitions''' directly.

At least trade-goods.plist , shipdata.plist , shipdata-overrides.plist , planetinfo.plist can set links to '''market scripts'''.

==== Which market scripts exactly? ====

See below.

==== What methods might lurk in ''any damned script''? ====

station.setMarketPrice() or
station.setMarketQuantity()

=== How do we define a new "trade-good" (commodity) '''non-bogusly?''' ===

With trade-goods.plist

=== How will sub-standard OXPs thwart us? ===

By careless use of "default" in market influences to destroy things they don't even know exist.

==== Can we move the world-script in AristoShares OXP into a market script? ====

That would prevent deadbeat scripts from interfering with it. Good idea, research required.

=== Can we define new properties for commodities? ===

Where can we set "aita_image" values?

=== Is the economy 0<->7 dipole set in stone? ===

Does it really require javascript to overcome this?

If so, what is the actual function of the peak_import & peak_export properties?

== Preamble ==

The trade-goods.plist file defines "trade goods" (commodities/cargo). But, it does not ''e.g.'' remove slaves from a particular station or make them cost twice as much as they do at the main orbital station. To do such things, ''i.e.'' to tweak the pricing/availability of commodities in a particular station, you need to define the market inside that station, either within its [[Shipdata.plist]] or within a [[Oolite_Market_Scripts|market script]] linked from its shipdata.plist.

== Overview ==

The '''trade-goods.plist''' file is a dictionary of dictionaries, with (canonical) commodity names as keys to dictionaries of key-value pairs 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 (listed thematically, not alphabetically) ==

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

=== market_script ===
The name of a Javascript file to use as a [[Oolite Market Scripts|market script]] for this trade good when calculating main station quantities and prices.

'''Note:''' [https://bb.oolite.space/viewtopic.php?p=235837#p235837 What's the difference between the market script specified in planetinfo.plist and the one called for by trade-goods.plist?] (2015)

=== classes ===
An array of commodity class names. Classes can be used by secondary stations (only secondary markets?) to set pricing rules for groups of commodities.

=== comment ===
A string that will be displayed on the F8 F8 commodity detail screen to describe the commodity. This can be modified later by [[Oolite_JavaScript_Reference:_Manifest#setComment|manifest.setComment()]]

=== 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 [[Oolite_JavaScript_Reference:_Manifest#setShortComment|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.

=== Legality ===

==== 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.

=== Economic biases ===

==== 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.

=== 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.

=== Quantities ===

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

==== 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.

=== Discussion of classes ===

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)

== Secondary Market Definitions ==

The primary market is that of the system's main station (''i.e.'' the javascript object system.mainStation.market ) Secondary markets are other markets, which are influenced by the primary market, ''e.g.'' that of a local Rock Hermit, or a visiting liner or another orbital station. Both quantities and prices will be influenced by those of the primary market. Needless to say, the primary market is randomly recalculated each time the system is visited.

Secondary market definitions are entered in the [[shipdata.plist#market_definition|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''':

# The market definition array is searched from top to bottom for the first element matching the trade good
# The market quantity is scaled in proportion to the relative capacities for that good in the two markets.
# 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|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 [[shipdata.plist#market_capacity|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 [[shipdata.plist#market_monitored|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.

=== Links ===
*[https://bb.oolite.space/viewtopic.php?f=2&t=21512 Secondary Market Definitions Defined] (2023)

== 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 for determining markets for new stations.

=== From the vanilla game: Rock Hermits ===
The "market_definition" 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: the Trade-goods.plist updated from the original 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;
};

}
=== A new commodity (from the trade-goods.plist inside "SW Economy") ===
"medicine" = {
"name" = "[commodity-name medicine]";
"classes" = ("oolite-consumer","oolite-medical");
"quantity_unit" = 1;
"peak_export" = 7;
"peak_import" = 0;
"price_average" = 640;
"price_economic" = 0.25;
"price_random" = 0.15;
"quantity_average" = 5;
"quantity_economic" = 1.5;
"quantity_random" = 1.0;
"legality_export" = 0;
"legality_import" = 0;
"trumble_opinion" = 0.50;
"sort_order" = 500;
"comment" = "[oolite-commodity-medicine]";
};

=== Setting an orbital main station's slaves on sale to zero ===
[[User:Phkb|Phkb]] provided this example which requires a ''planetinfo.plist'' & a new ''.js file'' - there are other ways to achieve the same result
==== 1) planetinfo.plist (to invoke the market script) ====
(in the "Config" folder)

{
"0 96" = {market_script = "digebiti_noslaves.js";};
}

==== 2) Market script: digebiti_noslaves.js ====
(in the "Scripts" folder) - note the complex name, which prevents confusion with other snippets of script

"use strict";
this.name = "digebiti_noslaves";
this.author = "Phkb";
this.copyright = "(C) 2022 Phkb";
this.licence = "CC-NC-by-SA 4.0";
this.description = "Removes slaves for sale in Digebiti";
this.version = "1.0";

this.updateLocalCommodityDefinition = function(goodDefinition, station, systemID) {
if (goodDefinition.key == "slaves" && station && station.isMainStation) {
goodDefinition.quantity = 0;
}
return goodDefinition;
}

This method will work, so long as no other OXP changes the market_script property of the Digebiti system in the same way.

=== Creating an invariant market independent of the local system economy (agricultural/industrial) ===
If you just use a market_definition in shipdata.plist for the station, then you're merely setting variations on the primary system market.

If you want the station prices to be independent of (or more loosely tied to) the system it's in, then you need to use a [[Oolite_Market_Scripts|market script]].

So what you'd have is something like this - let's say it's a hydroponics station, so it always sells food and nothing else, regardless of whether the general system economy is industrial or agricultural:

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.key == "food") {
// are we calculating the basic Oolite "food" trade good right now? If yes, set our own static prices
goodDefinition.price = 25; // 2.5 credits
goodDefinition.quantity = 80; // lots of food
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

Now ... the reason that market definitions are preferred to be mutators of the system economy is for two reasons.
1) it means you can avoid the situation where you end up with two adjacent stations with wildly different prices ... but you can of course handle that in other ways too, station positioning, restricted access, ''etc''.
2) it makes it easier to handle OXP trade goods:
- other OXPs might have added more "food" type goods, ''e.g.'' "Meat" or "Cheese"
- you can learn about those and handle them specifically

} else if (goodDefinition.key == "bobsfoodoxp_cheese") {
// set price and quantity here

... but that means a lot of keeping up with what everyone else is doing with custom goods.

The idea was that for your hydroponics station what you might do instead is something like this

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So now if another OXP adds Cheese, provided they declare it as "edible", your station will sell it in high quantities at a big discount, but you don't need to know exactly what the baseline price or quantity was set - so if a food-focused OXP was to add "Wine", "Fine Wine" and "Vintage Wine" at a range of prices and quantities, you'd be automatically handling those in reasonable line with a combination of the Wine OXP's basic pricing structure and your station OXP's "food primary source market" style, without necessarily needing to know about every future Wine OXP there might be and explicitly set compatibility.

Note in this example we're still zeroing out all non-food goods - OXP included! - regardless of the local economy. Maybe at this point we'd want to include and document a "hydroponicsoxp-agriculturalequipment" trade good class that other OXPs could use, which this station would buy up at higher demand and prices than normal.

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else if (goodDefinition.classes.indexOf("hydroponicsoxp-agriculturalequipment") >= 0) {
// custom class for other OXPs to add specific agricultural equipment e.g. combine harvesters, compost, fertiliser
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.capacity = 16; // buy a small amount only // TODO: raise capacity if price per tonne is low
goodDefinition.quantity = 0; // not selling this
} else if (goodDefinition.key == "machinery") {
// the basic Oolite Machinery commodity isn't in the custom class but we need to buy something if
// no OXPs adding it are installed
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.quantity = 0; // not selling
goodDefinition.capacity = 16; // small capacity to buy
} else {
// don't buy or sell any other commodity
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So you can see this one has a mix of using, mutating and overruling the definitions set by the system market and OXP commodity definitions ... with this method you could have a whole bunch of OXPs setting up themed stations, and a whole different bunch adding their own custom commodities, and they'd barely have to know about each other to ensure reasonable consistency and compatibility from someone installing any combination of them. (- by [[User:Cim|Cim]], 2023)

Note: this gives examples for 1 commodity at a time, but not how to easily do that for ALL the commodities on ALL the extra stations in a system.

== Using the trade-goods.plist ==
The trade-goods.plist was designed to make commodities simpler, by:
:1) Making it a dictionary rather than an unlabelled array so one could tell which parameter was which
:2) Making the price range for a trade good dependent on more sensible variables, so rather than setting the price range with a bitmask, one set the price and quantity variations dependent on the economy and on random chance.

Compare the v.1.81 trade-goods.plist with a v.1.80 commodities.plist - they were designed to give near-identical market behaviour for the built-in trade goods.

But - that only made it more comprehensible. It didn't really let one do anything particularly different to Elite 84 markets - mostly including the "Rich Industrial -> Poor Agricultural" single spectrum. One can tweak that a bit with peak_export and peak_import to get slightly different shapes (so a good might peak at Poor Industrial rather than Rich Industrial) but it doesn't really give one the option of a third economy type still.

''So how does one introduce a new economic pole, such as a mining industry?''

For that, one needs the scripting support. [[Oolite JavaScript Reference: Market Scripts]]. 
One can quite literally do whatever one likes with the prices that way. One could have every *system* have its own separate economy, which varied over time according to events, what the player had previously traded, ''etc. etc.'' to produce something comparable to Elite Dangerous' economic sim, if that's the route one wanted to go down. Obviously the more complexity one adds the harder it gets to script up, but it's now all possible.

[[File:SOTL Altmap F8.png|thumb|right|200px|SOTL Altmap F8 commodities market]]
[[SOTL Altmap]] does have an example of it, which basically throws out the original Elite-like algorithm of trade-goods.plist and starts over. It goes *way* beyond just adding a third economy, too.

Basically in SOTL every trade good is tagged in the trade-goods.plist with a bunch of classes
''e.g.''
classes = ("sotl-ex-salvage","sotl-im-refining","sotl-quantity-high","sotl-priceband-3","sotl-demand-medium","sotl-supply-medium","sotl-volatility-low");
So that means:
- exported by salvage economies
- imported by refining economies
- high quantity, moderate price, low price volatility

Then the market script uses those classes, rather than the standard pricing variables, to define the economic behaviour.
:So line 69-74ish: get the current economy description, convert that to the format used in the class name
:...line 85-90: check for the import and export classes for that economy and see if it's imported or exported
:...lines 100-120: apply various special conditions, so e.g. the sotl-ims-radiation class checks the planet surface radiation levels (custom property in sysinfo) and if the radiation level is high, imports these goods even if the basic economy isn't interested (e.g. "sotl-ceramics-ind" in the plist)
:...and then it uses those calculations (and a bunch more of the classes) in the rest of the script to set the price and quantity depending on whether it's an import, an export, or neither

That's massive overkill for just adding a third mining economy, but one would need to work on a similar principle.

:1) Tag every commodity with classes for (import|export|none)-(agricultural|industrial|mining) as appropriate
:2) Adjust the economy names (there are a few different ways one could do that) so that the 8 economy IDs were allocated to agricultural, industrial and mining economies
:3) Have a price script which like the SOTL one gets the current economy, looks at the classes list to find out if the commodity is imported or exported or neither, and sets the price and quantity accordingly. One could use the standard price_economic, price_average, price_random properties in the plist to give baseline data to the script if one was not planning to do anything too weird.

{Technically one doesn't need the classes - just have the price script contain a list of goods internally for each economy - but this way if other people add extra trade goods in their own OXPs, they can tag them up for mining economy support too}

All fairly straightforward theoretically.

''The biggest impediment to doing a wholesale reworking of the economic system, is just how incompatible it makes lots and lots of OXP's. In order to override the vanilla commodities as in SOTL, requires setting a script for each in trade-goods.plist. Which is fine if it's the only OXP that wants to play around with commodity prices. As soon as two OXP's try to do the same thing, one gets a conflict and no longer knows which OXP pricing model is in play.''

''For SOTL it's fine, because it uses the scenario system to forcibly eject all other OXP's from use while it's running. But if one wants the OXP to go in the general playing pool set of OXP's, it becomes much more complicated. [[User:Phkb|Phkb]] spent a long time trying to work out why his market script wasn't running, only to find that [[UPS Courier]] was quietly adjusting the markets in certain systems via the planetinfo.plist file. And there are a lot of OXP's that want to play in this space, tweaking prices up or down.''

''Hence one usually abandons using any of the script options, and just tweaks the price after all the scripts have finished playing, ''eg'' in [[Smugglers]]. It was the only way to guarantee getting some sort of bump in a price when wanted.''

== Links ==
*[[Oolite JavaScript Reference: Market Scripts]]
*[[Commodities.plist]] - the precursor (which still mostly works!). If it doesn't see [https://bb.oolite.space/viewtopic.php?p=246145#p246145 here] (2015)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16828 Proposal for 1.82: support for economic changes] ([[User:Cim|Cim]], 2014)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16735 Cim on introducing the Trade-goods.plist and deprecating the commodities.plist] (2014)
{{QuoteText|Text=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.|Source=([https://bb.oolite.space/viewtopic.php?p=226722#p226722 Cim in Progress Thread (2014)])}}
=== Using the Trade-goods.plist ===
*[https://bb.oolite.space/viewtopic.php?f=4&t=20576 How to get the displayName for a commodity in the Main Station Market?] (2020)
*[https://bb.oolite.space/viewtopic.php?f=6&t=17269 Thinking about Planet Income classification] (2015)

{{QuoteText|Text=
In 1.81 this is a lot easier to OXP - you can introduce as many economies as you like, though you are limited to eight economy symbols (so if you wanted lots of economy types, you might end up with Poor Industrial, Avg Industrial and Rich Industrial sharing a symbol on the map). The trade good pricing scripts can then be used to set up different price categories in different economies (and introduce additional trade goods, or split an existing good into multiple categories, which may be necessary if you're adding more economies).

Resetting economies across the planets is a big change in terms of lines of code, but is also very easy to automate. If OXPers are looking for a scripting tool to use for this sort of automation, then NodeJS or io.js is free and also uses Javascript as its language, so you don't need to learn a new one - and may even be able to share code between your build scripts and your OXP, though I haven't tried that yet.|Source=([https://bb.oolite.space/viewtopic.php?f=6&t=17269 Cim in Planet Income thread (2015)])}}

== Preamble ==
To tweak the pricing/availability of commodities in (''eg''.) a station, you need to define the market inside the station's Shipdata.plist - or include a "hook" inside that shipdata.plist to a javascript Oolite Market Script (which allows more complex definitions).

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:

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

== Handlers ==

=== updateGeneralCommodityDefinition ===
{{oolite-method-added|1.81}}
function updateGeneralCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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 = <code>false</code> 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 ===
{{oolite-method-added|1.81}}
function updateLocalCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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.

[https://bb.oolite.space/viewtopic.php?f=4&t=17621#p239979 Here is an example] of how to use this method.

== Links ==

=== Examples ===
*Phkb's update of [[SW_Economy]] (v.3.10) creates new economies for "mining worlds" (hewn out from some low tech poor agricultural worlds) with utterly different price scales for mineral, agricultural & industrial goods, as well as medicine.

''These others will be found at the bottom of the wiki page on the'' [[Trade-goods.plist]].
*Setting an orbital main station's slaves on sale to zero
*Creating an invariant market independent of the local system economy (agricultural/industrial)

Trade-goods (abridged)

2026-06-19T14:16:57Z

Wildeblood: /* Quantities */

'''You are probably looking for [[Trade-goods.plist]]''', rather than this page.

[[File:Distant Riches.png|thumb|right|200px|MORE THAN FIFTY NEW TRADE GOODS]]

== F.A.Q. ==

The goal of this page is to answer the following questions.

=== How many different places can market influences be hiding? ===

In plists, in market scripts, and in station methods in ''any damned script''.

==== Which plists exactly? ====

At least trade-goods.plist , shipdata.plist , shipdata-overrides.plist , planetinfo.plist can set '''market definitions''' directly.

At least trade-goods.plist , shipdata.plist , shipdata-overrides.plist , planetinfo.plist can set links to '''market scripts'''.

==== Which market scripts exactly? ====

See below.

==== What methods might lurk in ''any damned script''? ====

station.setMarketPrice() or
station.setMarketQuantity()

=== How do we define a new "trade-good" (commodity) '''non-bogusly?''' ===

With trade-goods.plist

=== How will sub-standard OXPs thwart us? ===

By careless use of "default" in market influences to destroy things they don't even know exist.

==== Can we move the world-script in AristoShares OXP into a market script? ====

That would prevent deadbeat scripts from interfering with it. Good idea, research required.

=== Can we define new properties for commodities? ===

Where can we set "aita_image" values?

=== Is the economy 0<->7 dipole set in stone? ===

Does it really require javascript to overcome this?

If so, what is the actual function of the peak_import & peak_export properties?

== Preamble ==

The trade-goods.plist file defines "trade goods" (commodities/cargo). But, it does not ''e.g.'' remove slaves from a particular station or make them cost twice as much as they do at the main orbital station. To do such things, ''i.e.'' to tweak the pricing/availability of commodities in a particular station, you need to define the market inside that station, either within its [[Shipdata.plist]] or within a [[Oolite_Market_Scripts|market script]] linked from its shipdata.plist.

== Overview ==

The '''trade-goods.plist''' file is a dictionary of dictionaries, with (canonical) commodity names as keys to dictionaries of key-value pairs 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 (listed thematically, not alphabetically) ==

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

=== market_script ===
The name of a Javascript file to use as a [[Oolite Market Scripts|market script]] for this trade good when calculating main station quantities and prices.

'''Note:''' [https://bb.oolite.space/viewtopic.php?p=235837#p235837 What's the difference between the market script specified in planetinfo.plist and the one called for by trade-goods.plist?] (2015)

=== classes ===
An array of commodity class names. Classes can be used by secondary stations (only secondary markets?) to set pricing rules for groups of commodities.

=== comment ===
A string that will be displayed on the F8 F8 commodity detail screen to describe the commodity. This can be modified later by [[Oolite_JavaScript_Reference:_Manifest#setComment|manifest.setComment()]]

=== 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 [[Oolite_JavaScript_Reference:_Manifest#setShortComment|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.

=== Legality ===

==== 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.

=== Economic biases ===

==== 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.

=== 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.

=== Quantities ===

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

==== 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.

=== Discussion of classes ===

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)

== Secondary Market Definitions ==

The primary market is that of the system's main station (''i.e.'' the javascript object system.mainStation.market ) Secondary markets are other markets, which are influenced by the primary market, ''e.g.'' that of a local Rock Hermit, or a visiting liner or another orbital station. Both quantities and prices will be influenced by those of the primary market. Needless to say, the primary market is randomly recalculated each time the system is visited.

Secondary market definitions are entered in the [[shipdata.plist#market_definition|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''':

# The market definition array is searched from top to bottom for the first element matching the trade good
# The market quantity is scaled in proportion to the relative capacities for that good in the two markets.
# 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|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 [[shipdata.plist#market_capacity|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 [[shipdata.plist#market_monitored|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.

=== Links ===
*[https://bb.oolite.space/viewtopic.php?f=2&t=21512 Secondary Market Definitions Defined] (2023)

== 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 for determining markets for new stations.

=== From the vanilla game: Rock Hermits ===
The "market_definition" 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: the Trade-goods.plist updated from the original 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;
};

}
=== A new commodity (from the trade-goods.plist inside "SW Economy") ===
"medicine" = {
"name" = "[commodity-name medicine]";
"classes" = ("oolite-consumer","oolite-medical");
"quantity_unit" = 1;
"peak_export" = 7;
"peak_import" = 0;
"price_average" = 640;
"price_economic" = 0.25;
"price_random" = 0.15;
"quantity_average" = 5;
"quantity_economic" = 1.5;
"quantity_random" = 1.0;
"legality_export" = 0;
"legality_import" = 0;
"trumble_opinion" = 0.50;
"sort_order" = 500;
"comment" = "[oolite-commodity-medicine]";
};

=== Setting an orbital main station's slaves on sale to zero ===
[[User:Phkb|Phkb]] provided this example which requires a ''planetinfo.plist'' & a new ''.js file'' - there are other ways to achieve the same result
==== 1) planetinfo.plist (to invoke the market script) ====
(in the "Config" folder)

{
"0 96" = {market_script = "digebiti_noslaves.js";};
}

==== 2) Market script: digebiti_noslaves.js ====
(in the "Scripts" folder) - note the complex name, which prevents confusion with other snippets of script

"use strict";
this.name = "digebiti_noslaves";
this.author = "Phkb";
this.copyright = "(C) 2022 Phkb";
this.licence = "CC-NC-by-SA 4.0";
this.description = "Removes slaves for sale in Digebiti";
this.version = "1.0";

this.updateLocalCommodityDefinition = function(goodDefinition, station, systemID) {
if (goodDefinition.key == "slaves" && station && station.isMainStation) {
goodDefinition.quantity = 0;
}
return goodDefinition;
}

This method will work, so long as no other OXP changes the market_script property of the Digebiti system in the same way.

=== Creating an invariant market independent of the local system economy (agricultural/industrial) ===
If you just use a market_definition in shipdata.plist for the station, then you're merely setting variations on the primary system market.

If you want the station prices to be independent of (or more loosely tied to) the system it's in, then you need to use a [[Oolite_Market_Scripts|market script]].

So what you'd have is something like this - let's say it's a hydroponics station, so it always sells food and nothing else, regardless of whether the general system economy is industrial or agricultural:

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.key == "food") {
// are we calculating the basic Oolite "food" trade good right now? If yes, set our own static prices
goodDefinition.price = 25; // 2.5 credits
goodDefinition.quantity = 80; // lots of food
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

Now ... the reason that market definitions are preferred to be mutators of the system economy is for two reasons.
1) it means you can avoid the situation where you end up with two adjacent stations with wildly different prices ... but you can of course handle that in other ways too, station positioning, restricted access, ''etc''.
2) it makes it easier to handle OXP trade goods:
- other OXPs might have added more "food" type goods, ''e.g.'' "Meat" or "Cheese"
- you can learn about those and handle them specifically

} else if (goodDefinition.key == "bobsfoodoxp_cheese") {
// set price and quantity here

... but that means a lot of keeping up with what everyone else is doing with custom goods.

The idea was that for your hydroponics station what you might do instead is something like this

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So now if another OXP adds Cheese, provided they declare it as "edible", your station will sell it in high quantities at a big discount, but you don't need to know exactly what the baseline price or quantity was set - so if a food-focused OXP was to add "Wine", "Fine Wine" and "Vintage Wine" at a range of prices and quantities, you'd be automatically handling those in reasonable line with a combination of the Wine OXP's basic pricing structure and your station OXP's "food primary source market" style, without necessarily needing to know about every future Wine OXP there might be and explicitly set compatibility.

Note in this example we're still zeroing out all non-food goods - OXP included! - regardless of the local economy. Maybe at this point we'd want to include and document a "hydroponicsoxp-agriculturalequipment" trade good class that other OXPs could use, which this station would buy up at higher demand and prices than normal.

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else if (goodDefinition.classes.indexOf("hydroponicsoxp-agriculturalequipment") >= 0) {
// custom class for other OXPs to add specific agricultural equipment e.g. combine harvesters, compost, fertiliser
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.capacity = 16; // buy a small amount only // TODO: raise capacity if price per tonne is low
goodDefinition.quantity = 0; // not selling this
} else if (goodDefinition.key == "machinery") {
// the basic Oolite Machinery commodity isn't in the custom class but we need to buy something if
// no OXPs adding it are installed
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.quantity = 0; // not selling
goodDefinition.capacity = 16; // small capacity to buy
} else {
// don't buy or sell any other commodity
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So you can see this one has a mix of using, mutating and overruling the definitions set by the system market and OXP commodity definitions ... with this method you could have a whole bunch of OXPs setting up themed stations, and a whole different bunch adding their own custom commodities, and they'd barely have to know about each other to ensure reasonable consistency and compatibility from someone installing any combination of them. (- by [[User:Cim|Cim]], 2023)

Note: this gives examples for 1 commodity at a time, but not how to easily do that for ALL the commodities on ALL the extra stations in a system.

== Using the trade-goods.plist ==
The trade-goods.plist was designed to make commodities simpler, by:
:1) Making it a dictionary rather than an unlabelled array so one could tell which parameter was which
:2) Making the price range for a trade good dependent on more sensible variables, so rather than setting the price range with a bitmask, one set the price and quantity variations dependent on the economy and on random chance.

Compare the v.1.81 trade-goods.plist with a v.1.80 commodities.plist - they were designed to give near-identical market behaviour for the built-in trade goods.

But - that only made it more comprehensible. It didn't really let one do anything particularly different to Elite 84 markets - mostly including the "Rich Industrial -> Poor Agricultural" single spectrum. One can tweak that a bit with peak_export and peak_import to get slightly different shapes (so a good might peak at Poor Industrial rather than Rich Industrial) but it doesn't really give one the option of a third economy type still.

''So how does one introduce a new economic pole, such as a mining industry?''

For that, one needs the scripting support. [[Oolite JavaScript Reference: Market Scripts]]. 
One can quite literally do whatever one likes with the prices that way. One could have every *system* have its own separate economy, which varied over time according to events, what the player had previously traded, ''etc. etc.'' to produce something comparable to Elite Dangerous' economic sim, if that's the route one wanted to go down. Obviously the more complexity one adds the harder it gets to script up, but it's now all possible.

[[File:SOTL Altmap F8.png|thumb|right|200px|SOTL Altmap F8 commodities market]]
[[SOTL Altmap]] does have an example of it, which basically throws out the original Elite-like algorithm of trade-goods.plist and starts over. It goes *way* beyond just adding a third economy, too.

Basically in SOTL every trade good is tagged in the trade-goods.plist with a bunch of classes
''e.g.''
classes = ("sotl-ex-salvage","sotl-im-refining","sotl-quantity-high","sotl-priceband-3","sotl-demand-medium","sotl-supply-medium","sotl-volatility-low");
So that means:
- exported by salvage economies
- imported by refining economies
- high quantity, moderate price, low price volatility

Then the market script uses those classes, rather than the standard pricing variables, to define the economic behaviour.
:So line 69-74ish: get the current economy description, convert that to the format used in the class name
:...line 85-90: check for the import and export classes for that economy and see if it's imported or exported
:...lines 100-120: apply various special conditions, so e.g. the sotl-ims-radiation class checks the planet surface radiation levels (custom property in sysinfo) and if the radiation level is high, imports these goods even if the basic economy isn't interested (e.g. "sotl-ceramics-ind" in the plist)
:...and then it uses those calculations (and a bunch more of the classes) in the rest of the script to set the price and quantity depending on whether it's an import, an export, or neither

That's massive overkill for just adding a third mining economy, but one would need to work on a similar principle.

:1) Tag every commodity with classes for (import|export|none)-(agricultural|industrial|mining) as appropriate
:2) Adjust the economy names (there are a few different ways one could do that) so that the 8 economy IDs were allocated to agricultural, industrial and mining economies
:3) Have a price script which like the SOTL one gets the current economy, looks at the classes list to find out if the commodity is imported or exported or neither, and sets the price and quantity accordingly. One could use the standard price_economic, price_average, price_random properties in the plist to give baseline data to the script if one was not planning to do anything too weird.

{Technically one doesn't need the classes - just have the price script contain a list of goods internally for each economy - but this way if other people add extra trade goods in their own OXPs, they can tag them up for mining economy support too}

All fairly straightforward theoretically.

''The biggest impediment to doing a wholesale reworking of the economic system, is just how incompatible it makes lots and lots of OXP's. In order to override the vanilla commodities as in SOTL, requires setting a script for each in trade-goods.plist. Which is fine if it's the only OXP that wants to play around with commodity prices. As soon as two OXP's try to do the same thing, one gets a conflict and no longer knows which OXP pricing model is in play.''

''For SOTL it's fine, because it uses the scenario system to forcibly eject all other OXP's from use while it's running. But if one wants the OXP to go in the general playing pool set of OXP's, it becomes much more complicated. [[User:Phkb|Phkb]] spent a long time trying to work out why his market script wasn't running, only to find that [[UPS Courier]] was quietly adjusting the markets in certain systems via the planetinfo.plist file. And there are a lot of OXP's that want to play in this space, tweaking prices up or down.''

''Hence one usually abandons using any of the script options, and just tweaks the price after all the scripts have finished playing, ''eg'' in [[Smugglers]]. It was the only way to guarantee getting some sort of bump in a price when wanted.''

== Links ==
*[[Oolite JavaScript Reference: Market Scripts]]
*[[Commodities.plist]] - the precursor (which still mostly works!). If it doesn't see [https://bb.oolite.space/viewtopic.php?p=246145#p246145 here] (2015)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16828 Proposal for 1.82: support for economic changes] ([[User:Cim|Cim]], 2014)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16735 Cim on introducing the Trade-goods.plist and deprecating the commodities.plist] (2014)
{{QuoteText|Text=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.|Source=([https://bb.oolite.space/viewtopic.php?p=226722#p226722 Cim in Progress Thread (2014)])}}
=== Using the Trade-goods.plist ===
*[https://bb.oolite.space/viewtopic.php?f=4&t=20576 How to get the displayName for a commodity in the Main Station Market?] (2020)
*[https://bb.oolite.space/viewtopic.php?f=6&t=17269 Thinking about Planet Income classification] (2015)

{{QuoteText|Text=
In 1.81 this is a lot easier to OXP - you can introduce as many economies as you like, though you are limited to eight economy symbols (so if you wanted lots of economy types, you might end up with Poor Industrial, Avg Industrial and Rich Industrial sharing a symbol on the map). The trade good pricing scripts can then be used to set up different price categories in different economies (and introduce additional trade goods, or split an existing good into multiple categories, which may be necessary if you're adding more economies).

Resetting economies across the planets is a big change in terms of lines of code, but is also very easy to automate. If OXPers are looking for a scripting tool to use for this sort of automation, then NodeJS or io.js is free and also uses Javascript as its language, so you don't need to learn a new one - and may even be able to share code between your build scripts and your OXP, though I haven't tried that yet.|Source=([https://bb.oolite.space/viewtopic.php?f=6&t=17269 Cim in Planet Income thread (2015)])}}

== Preamble ==
To tweak the pricing/availability of commodities in (''eg''.) a station, you need to define the market inside the station's Shipdata.plist - or include a "hook" inside that shipdata.plist to a javascript Oolite Market Script (which allows more complex definitions).

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:

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

== Handlers ==

=== updateGeneralCommodityDefinition ===
{{oolite-method-added|1.81}}
function updateGeneralCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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 = <code>false</code> 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 ===
{{oolite-method-added|1.81}}
function updateLocalCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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.

[https://bb.oolite.space/viewtopic.php?f=4&t=17621#p239979 Here is an example] of how to use this method.

== Links ==

=== Examples ===
*Phkb's update of [[SW_Economy]] (v.3.10) creates new economies for "mining worlds" (hewn out from some low tech poor agricultural worlds) with utterly different price scales for mineral, agricultural & industrial goods, as well as medicine.

''These others will be found at the bottom of the wiki page on the'' [[Trade-goods.plist]].
*Setting an orbital main station's slaves on sale to zero
*Creating an invariant market independent of the local system economy (agricultural/industrial)

Trade-goods (abridged)

2026-06-19T14:16:13Z

Wildeblood: /* capacity */

'''You are probably looking for [[Trade-goods.plist]]''', rather than this page.

[[File:Distant Riches.png|thumb|right|200px|MORE THAN FIFTY NEW TRADE GOODS]]

== F.A.Q. ==

The goal of this page is to answer the following questions.

=== How many different places can market influences be hiding? ===

In plists, in market scripts, and in station methods in ''any damned script''.

==== Which plists exactly? ====

At least trade-goods.plist , shipdata.plist , shipdata-overrides.plist , planetinfo.plist can set '''market definitions''' directly.

At least trade-goods.plist , shipdata.plist , shipdata-overrides.plist , planetinfo.plist can set links to '''market scripts'''.

==== Which market scripts exactly? ====

See below.

==== What methods might lurk in ''any damned script''? ====

station.setMarketPrice() or
station.setMarketQuantity()

=== How do we define a new "trade-good" (commodity) '''non-bogusly?''' ===

With trade-goods.plist

=== How will sub-standard OXPs thwart us? ===

By careless use of "default" in market influences to destroy things they don't even know exist.

==== Can we move the world-script in AristoShares OXP into a market script? ====

That would prevent deadbeat scripts from interfering with it. Good idea, research required.

=== Can we define new properties for commodities? ===

Where can we set "aita_image" values?

=== Is the economy 0<->7 dipole set in stone? ===

Does it really require javascript to overcome this?

If so, what is the actual function of the peak_import & peak_export properties?

== Preamble ==

The trade-goods.plist file defines "trade goods" (commodities/cargo). But, it does not ''e.g.'' remove slaves from a particular station or make them cost twice as much as they do at the main orbital station. To do such things, ''i.e.'' to tweak the pricing/availability of commodities in a particular station, you need to define the market inside that station, either within its [[Shipdata.plist]] or within a [[Oolite_Market_Scripts|market script]] linked from its shipdata.plist.

== Overview ==

The '''trade-goods.plist''' file is a dictionary of dictionaries, with (canonical) commodity names as keys to dictionaries of key-value pairs 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 (listed thematically, not alphabetically) ==

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

=== market_script ===
The name of a Javascript file to use as a [[Oolite Market Scripts|market script]] for this trade good when calculating main station quantities and prices.

'''Note:''' [https://bb.oolite.space/viewtopic.php?p=235837#p235837 What's the difference between the market script specified in planetinfo.plist and the one called for by trade-goods.plist?] (2015)

=== classes ===
An array of commodity class names. Classes can be used by secondary stations (only secondary markets?) to set pricing rules for groups of commodities.

=== comment ===
A string that will be displayed on the F8 F8 commodity detail screen to describe the commodity. This can be modified later by [[Oolite_JavaScript_Reference:_Manifest#setComment|manifest.setComment()]]

=== 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 [[Oolite_JavaScript_Reference:_Manifest#setShortComment|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.

=== Legality ===

==== 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.

=== Economic biases ===

==== 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.

=== 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.

=== Quantities ===

==== 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.

=== Discussion of classes ===

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)

== Secondary Market Definitions ==

The primary market is that of the system's main station (''i.e.'' the javascript object system.mainStation.market ) Secondary markets are other markets, which are influenced by the primary market, ''e.g.'' that of a local Rock Hermit, or a visiting liner or another orbital station. Both quantities and prices will be influenced by those of the primary market. Needless to say, the primary market is randomly recalculated each time the system is visited.

Secondary market definitions are entered in the [[shipdata.plist#market_definition|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''':

# The market definition array is searched from top to bottom for the first element matching the trade good
# The market quantity is scaled in proportion to the relative capacities for that good in the two markets.
# 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|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 [[shipdata.plist#market_capacity|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 [[shipdata.plist#market_monitored|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.

=== Links ===
*[https://bb.oolite.space/viewtopic.php?f=2&t=21512 Secondary Market Definitions Defined] (2023)

== 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 for determining markets for new stations.

=== From the vanilla game: Rock Hermits ===
The "market_definition" 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: the Trade-goods.plist updated from the original 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;
};

}
=== A new commodity (from the trade-goods.plist inside "SW Economy") ===
"medicine" = {
"name" = "[commodity-name medicine]";
"classes" = ("oolite-consumer","oolite-medical");
"quantity_unit" = 1;
"peak_export" = 7;
"peak_import" = 0;
"price_average" = 640;
"price_economic" = 0.25;
"price_random" = 0.15;
"quantity_average" = 5;
"quantity_economic" = 1.5;
"quantity_random" = 1.0;
"legality_export" = 0;
"legality_import" = 0;
"trumble_opinion" = 0.50;
"sort_order" = 500;
"comment" = "[oolite-commodity-medicine]";
};

=== Setting an orbital main station's slaves on sale to zero ===
[[User:Phkb|Phkb]] provided this example which requires a ''planetinfo.plist'' & a new ''.js file'' - there are other ways to achieve the same result
==== 1) planetinfo.plist (to invoke the market script) ====
(in the "Config" folder)

{
"0 96" = {market_script = "digebiti_noslaves.js";};
}

==== 2) Market script: digebiti_noslaves.js ====
(in the "Scripts" folder) - note the complex name, which prevents confusion with other snippets of script

"use strict";
this.name = "digebiti_noslaves";
this.author = "Phkb";
this.copyright = "(C) 2022 Phkb";
this.licence = "CC-NC-by-SA 4.0";
this.description = "Removes slaves for sale in Digebiti";
this.version = "1.0";

this.updateLocalCommodityDefinition = function(goodDefinition, station, systemID) {
if (goodDefinition.key == "slaves" && station && station.isMainStation) {
goodDefinition.quantity = 0;
}
return goodDefinition;
}

This method will work, so long as no other OXP changes the market_script property of the Digebiti system in the same way.

=== Creating an invariant market independent of the local system economy (agricultural/industrial) ===
If you just use a market_definition in shipdata.plist for the station, then you're merely setting variations on the primary system market.

If you want the station prices to be independent of (or more loosely tied to) the system it's in, then you need to use a [[Oolite_Market_Scripts|market script]].

So what you'd have is something like this - let's say it's a hydroponics station, so it always sells food and nothing else, regardless of whether the general system economy is industrial or agricultural:

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.key == "food") {
// are we calculating the basic Oolite "food" trade good right now? If yes, set our own static prices
goodDefinition.price = 25; // 2.5 credits
goodDefinition.quantity = 80; // lots of food
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

Now ... the reason that market definitions are preferred to be mutators of the system economy is for two reasons.
1) it means you can avoid the situation where you end up with two adjacent stations with wildly different prices ... but you can of course handle that in other ways too, station positioning, restricted access, ''etc''.
2) it makes it easier to handle OXP trade goods:
- other OXPs might have added more "food" type goods, ''e.g.'' "Meat" or "Cheese"
- you can learn about those and handle them specifically

} else if (goodDefinition.key == "bobsfoodoxp_cheese") {
// set price and quantity here

... but that means a lot of keeping up with what everyone else is doing with custom goods.

The idea was that for your hydroponics station what you might do instead is something like this

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So now if another OXP adds Cheese, provided they declare it as "edible", your station will sell it in high quantities at a big discount, but you don't need to know exactly what the baseline price or quantity was set - so if a food-focused OXP was to add "Wine", "Fine Wine" and "Vintage Wine" at a range of prices and quantities, you'd be automatically handling those in reasonable line with a combination of the Wine OXP's basic pricing structure and your station OXP's "food primary source market" style, without necessarily needing to know about every future Wine OXP there might be and explicitly set compatibility.

Note in this example we're still zeroing out all non-food goods - OXP included! - regardless of the local economy. Maybe at this point we'd want to include and document a "hydroponicsoxp-agriculturalequipment" trade good class that other OXPs could use, which this station would buy up at higher demand and prices than normal.

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else if (goodDefinition.classes.indexOf("hydroponicsoxp-agriculturalequipment") >= 0) {
// custom class for other OXPs to add specific agricultural equipment e.g. combine harvesters, compost, fertiliser
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.capacity = 16; // buy a small amount only // TODO: raise capacity if price per tonne is low
goodDefinition.quantity = 0; // not selling this
} else if (goodDefinition.key == "machinery") {
// the basic Oolite Machinery commodity isn't in the custom class but we need to buy something if
// no OXPs adding it are installed
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.quantity = 0; // not selling
goodDefinition.capacity = 16; // small capacity to buy
} else {
// don't buy or sell any other commodity
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So you can see this one has a mix of using, mutating and overruling the definitions set by the system market and OXP commodity definitions ... with this method you could have a whole bunch of OXPs setting up themed stations, and a whole different bunch adding their own custom commodities, and they'd barely have to know about each other to ensure reasonable consistency and compatibility from someone installing any combination of them. (- by [[User:Cim|Cim]], 2023)

Note: this gives examples for 1 commodity at a time, but not how to easily do that for ALL the commodities on ALL the extra stations in a system.

== Using the trade-goods.plist ==
The trade-goods.plist was designed to make commodities simpler, by:
:1) Making it a dictionary rather than an unlabelled array so one could tell which parameter was which
:2) Making the price range for a trade good dependent on more sensible variables, so rather than setting the price range with a bitmask, one set the price and quantity variations dependent on the economy and on random chance.

Compare the v.1.81 trade-goods.plist with a v.1.80 commodities.plist - they were designed to give near-identical market behaviour for the built-in trade goods.

But - that only made it more comprehensible. It didn't really let one do anything particularly different to Elite 84 markets - mostly including the "Rich Industrial -> Poor Agricultural" single spectrum. One can tweak that a bit with peak_export and peak_import to get slightly different shapes (so a good might peak at Poor Industrial rather than Rich Industrial) but it doesn't really give one the option of a third economy type still.

''So how does one introduce a new economic pole, such as a mining industry?''

For that, one needs the scripting support. [[Oolite JavaScript Reference: Market Scripts]]. 
One can quite literally do whatever one likes with the prices that way. One could have every *system* have its own separate economy, which varied over time according to events, what the player had previously traded, ''etc. etc.'' to produce something comparable to Elite Dangerous' economic sim, if that's the route one wanted to go down. Obviously the more complexity one adds the harder it gets to script up, but it's now all possible.

[[File:SOTL Altmap F8.png|thumb|right|200px|SOTL Altmap F8 commodities market]]
[[SOTL Altmap]] does have an example of it, which basically throws out the original Elite-like algorithm of trade-goods.plist and starts over. It goes *way* beyond just adding a third economy, too.

Basically in SOTL every trade good is tagged in the trade-goods.plist with a bunch of classes
''e.g.''
classes = ("sotl-ex-salvage","sotl-im-refining","sotl-quantity-high","sotl-priceband-3","sotl-demand-medium","sotl-supply-medium","sotl-volatility-low");
So that means:
- exported by salvage economies
- imported by refining economies
- high quantity, moderate price, low price volatility

Then the market script uses those classes, rather than the standard pricing variables, to define the economic behaviour.
:So line 69-74ish: get the current economy description, convert that to the format used in the class name
:...line 85-90: check for the import and export classes for that economy and see if it's imported or exported
:...lines 100-120: apply various special conditions, so e.g. the sotl-ims-radiation class checks the planet surface radiation levels (custom property in sysinfo) and if the radiation level is high, imports these goods even if the basic economy isn't interested (e.g. "sotl-ceramics-ind" in the plist)
:...and then it uses those calculations (and a bunch more of the classes) in the rest of the script to set the price and quantity depending on whether it's an import, an export, or neither

That's massive overkill for just adding a third mining economy, but one would need to work on a similar principle.

:1) Tag every commodity with classes for (import|export|none)-(agricultural|industrial|mining) as appropriate
:2) Adjust the economy names (there are a few different ways one could do that) so that the 8 economy IDs were allocated to agricultural, industrial and mining economies
:3) Have a price script which like the SOTL one gets the current economy, looks at the classes list to find out if the commodity is imported or exported or neither, and sets the price and quantity accordingly. One could use the standard price_economic, price_average, price_random properties in the plist to give baseline data to the script if one was not planning to do anything too weird.

{Technically one doesn't need the classes - just have the price script contain a list of goods internally for each economy - but this way if other people add extra trade goods in their own OXPs, they can tag them up for mining economy support too}

All fairly straightforward theoretically.

''The biggest impediment to doing a wholesale reworking of the economic system, is just how incompatible it makes lots and lots of OXP's. In order to override the vanilla commodities as in SOTL, requires setting a script for each in trade-goods.plist. Which is fine if it's the only OXP that wants to play around with commodity prices. As soon as two OXP's try to do the same thing, one gets a conflict and no longer knows which OXP pricing model is in play.''

''For SOTL it's fine, because it uses the scenario system to forcibly eject all other OXP's from use while it's running. But if one wants the OXP to go in the general playing pool set of OXP's, it becomes much more complicated. [[User:Phkb|Phkb]] spent a long time trying to work out why his market script wasn't running, only to find that [[UPS Courier]] was quietly adjusting the markets in certain systems via the planetinfo.plist file. And there are a lot of OXP's that want to play in this space, tweaking prices up or down.''

''Hence one usually abandons using any of the script options, and just tweaks the price after all the scripts have finished playing, ''eg'' in [[Smugglers]]. It was the only way to guarantee getting some sort of bump in a price when wanted.''

== Links ==
*[[Oolite JavaScript Reference: Market Scripts]]
*[[Commodities.plist]] - the precursor (which still mostly works!). If it doesn't see [https://bb.oolite.space/viewtopic.php?p=246145#p246145 here] (2015)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16828 Proposal for 1.82: support for economic changes] ([[User:Cim|Cim]], 2014)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16735 Cim on introducing the Trade-goods.plist and deprecating the commodities.plist] (2014)
{{QuoteText|Text=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.|Source=([https://bb.oolite.space/viewtopic.php?p=226722#p226722 Cim in Progress Thread (2014)])}}
=== Using the Trade-goods.plist ===
*[https://bb.oolite.space/viewtopic.php?f=4&t=20576 How to get the displayName for a commodity in the Main Station Market?] (2020)
*[https://bb.oolite.space/viewtopic.php?f=6&t=17269 Thinking about Planet Income classification] (2015)

{{QuoteText|Text=
In 1.81 this is a lot easier to OXP - you can introduce as many economies as you like, though you are limited to eight economy symbols (so if you wanted lots of economy types, you might end up with Poor Industrial, Avg Industrial and Rich Industrial sharing a symbol on the map). The trade good pricing scripts can then be used to set up different price categories in different economies (and introduce additional trade goods, or split an existing good into multiple categories, which may be necessary if you're adding more economies).

Resetting economies across the planets is a big change in terms of lines of code, but is also very easy to automate. If OXPers are looking for a scripting tool to use for this sort of automation, then NodeJS or io.js is free and also uses Javascript as its language, so you don't need to learn a new one - and may even be able to share code between your build scripts and your OXP, though I haven't tried that yet.|Source=([https://bb.oolite.space/viewtopic.php?f=6&t=17269 Cim in Planet Income thread (2015)])}}

== Preamble ==
To tweak the pricing/availability of commodities in (''eg''.) a station, you need to define the market inside the station's Shipdata.plist - or include a "hook" inside that shipdata.plist to a javascript Oolite Market Script (which allows more complex definitions).

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:

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

== Handlers ==

=== updateGeneralCommodityDefinition ===
{{oolite-method-added|1.81}}
function updateGeneralCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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 = <code>false</code> 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 ===
{{oolite-method-added|1.81}}
function updateLocalCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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.

[https://bb.oolite.space/viewtopic.php?f=4&t=17621#p239979 Here is an example] of how to use this method.

== Links ==

=== Examples ===
*Phkb's update of [[SW_Economy]] (v.3.10) creates new economies for "mining worlds" (hewn out from some low tech poor agricultural worlds) with utterly different price scales for mineral, agricultural & industrial goods, as well as medicine.

''These others will be found at the bottom of the wiki page on the'' [[Trade-goods.plist]].
*Setting an orbital main station's slaves on sale to zero
*Creating an invariant market independent of the local system economy (agricultural/industrial)

Trade-goods (abridged)

2026-06-19T14:04:44Z

Wildeblood: /* Property keys (listed thematically, not alphabetically) */

'''You are probably looking for [[Trade-goods.plist]]''', rather than this page.

[[File:Distant Riches.png|thumb|right|200px|MORE THAN FIFTY NEW TRADE GOODS]]

== F.A.Q. ==

The goal of this page is to answer the following questions.

=== How many different places can market influences be hiding? ===

In plists, in market scripts, and in station methods in ''any damned script''.

==== Which plists exactly? ====

At least trade-goods.plist , shipdata.plist , shipdata-overrides.plist , planetinfo.plist can set '''market definitions''' directly.

At least trade-goods.plist , shipdata.plist , shipdata-overrides.plist , planetinfo.plist can set links to '''market scripts'''.

==== Which market scripts exactly? ====

See below.

==== What methods might lurk in ''any damned script''? ====

station.setMarketPrice() or
station.setMarketQuantity()

=== How do we define a new "trade-good" (commodity) '''non-bogusly?''' ===

With trade-goods.plist

=== How will sub-standard OXPs thwart us? ===

By careless use of "default" in market influences to destroy things they don't even know exist.

==== Can we move the world-script in AristoShares OXP into a market script? ====

That would prevent deadbeat scripts from interfering with it. Good idea, research required.

=== Can we define new properties for commodities? ===

Where can we set "aita_image" values?

=== Is the economy 0<->7 dipole set in stone? ===

Does it really require javascript to overcome this?

If so, what is the actual function of the peak_import & peak_export properties?

== Preamble ==

The trade-goods.plist file defines "trade goods" (commodities/cargo). But, it does not ''e.g.'' remove slaves from a particular station or make them cost twice as much as they do at the main orbital station. To do such things, ''i.e.'' to tweak the pricing/availability of commodities in a particular station, you need to define the market inside that station, either within its [[Shipdata.plist]] or within a [[Oolite_Market_Scripts|market script]] linked from its shipdata.plist.

== Overview ==

The '''trade-goods.plist''' file is a dictionary of dictionaries, with (canonical) commodity names as keys to dictionaries of key-value pairs 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 (listed thematically, not alphabetically) ==

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

=== market_script ===
The name of a Javascript file to use as a [[Oolite Market Scripts|market script]] for this trade good when calculating main station quantities and prices.

'''Note:''' [https://bb.oolite.space/viewtopic.php?p=235837#p235837 What's the difference between the market script specified in planetinfo.plist and the one called for by trade-goods.plist?] (2015)

=== 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 commodity class names. Classes can be used by secondary stations (only secondary markets?) to set pricing rules for groups of commodities.

=== comment ===
A string that will be displayed on the F8 F8 commodity detail screen to describe the commodity. This can be modified later by [[Oolite_JavaScript_Reference:_Manifest#setComment|manifest.setComment()]]

=== 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 [[Oolite_JavaScript_Reference:_Manifest#setShortComment|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.

=== Legality ===

==== 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.

=== Economic biases ===

==== 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.

=== 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.

=== Quantities ===

==== 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.

=== Discussion of classes ===

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)

== Secondary Market Definitions ==

The primary market is that of the system's main station (''i.e.'' the javascript object system.mainStation.market ) Secondary markets are other markets, which are influenced by the primary market, ''e.g.'' that of a local Rock Hermit, or a visiting liner or another orbital station. Both quantities and prices will be influenced by those of the primary market. Needless to say, the primary market is randomly recalculated each time the system is visited.

Secondary market definitions are entered in the [[shipdata.plist#market_definition|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''':

# The market definition array is searched from top to bottom for the first element matching the trade good
# The market quantity is scaled in proportion to the relative capacities for that good in the two markets.
# 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|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 [[shipdata.plist#market_capacity|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 [[shipdata.plist#market_monitored|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.

=== Links ===
*[https://bb.oolite.space/viewtopic.php?f=2&t=21512 Secondary Market Definitions Defined] (2023)

== 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 for determining markets for new stations.

=== From the vanilla game: Rock Hermits ===
The "market_definition" 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: the Trade-goods.plist updated from the original 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;
};

}
=== A new commodity (from the trade-goods.plist inside "SW Economy") ===
"medicine" = {
"name" = "[commodity-name medicine]";
"classes" = ("oolite-consumer","oolite-medical");
"quantity_unit" = 1;
"peak_export" = 7;
"peak_import" = 0;
"price_average" = 640;
"price_economic" = 0.25;
"price_random" = 0.15;
"quantity_average" = 5;
"quantity_economic" = 1.5;
"quantity_random" = 1.0;
"legality_export" = 0;
"legality_import" = 0;
"trumble_opinion" = 0.50;
"sort_order" = 500;
"comment" = "[oolite-commodity-medicine]";
};

=== Setting an orbital main station's slaves on sale to zero ===
[[User:Phkb|Phkb]] provided this example which requires a ''planetinfo.plist'' & a new ''.js file'' - there are other ways to achieve the same result
==== 1) planetinfo.plist (to invoke the market script) ====
(in the "Config" folder)

{
"0 96" = {market_script = "digebiti_noslaves.js";};
}

==== 2) Market script: digebiti_noslaves.js ====
(in the "Scripts" folder) - note the complex name, which prevents confusion with other snippets of script

"use strict";
this.name = "digebiti_noslaves";
this.author = "Phkb";
this.copyright = "(C) 2022 Phkb";
this.licence = "CC-NC-by-SA 4.0";
this.description = "Removes slaves for sale in Digebiti";
this.version = "1.0";

this.updateLocalCommodityDefinition = function(goodDefinition, station, systemID) {
if (goodDefinition.key == "slaves" && station && station.isMainStation) {
goodDefinition.quantity = 0;
}
return goodDefinition;
}

This method will work, so long as no other OXP changes the market_script property of the Digebiti system in the same way.

=== Creating an invariant market independent of the local system economy (agricultural/industrial) ===
If you just use a market_definition in shipdata.plist for the station, then you're merely setting variations on the primary system market.

If you want the station prices to be independent of (or more loosely tied to) the system it's in, then you need to use a [[Oolite_Market_Scripts|market script]].

So what you'd have is something like this - let's say it's a hydroponics station, so it always sells food and nothing else, regardless of whether the general system economy is industrial or agricultural:

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.key == "food") {
// are we calculating the basic Oolite "food" trade good right now? If yes, set our own static prices
goodDefinition.price = 25; // 2.5 credits
goodDefinition.quantity = 80; // lots of food
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

Now ... the reason that market definitions are preferred to be mutators of the system economy is for two reasons.
1) it means you can avoid the situation where you end up with two adjacent stations with wildly different prices ... but you can of course handle that in other ways too, station positioning, restricted access, ''etc''.
2) it makes it easier to handle OXP trade goods:
- other OXPs might have added more "food" type goods, ''e.g.'' "Meat" or "Cheese"
- you can learn about those and handle them specifically

} else if (goodDefinition.key == "bobsfoodoxp_cheese") {
// set price and quantity here

... but that means a lot of keeping up with what everyone else is doing with custom goods.

The idea was that for your hydroponics station what you might do instead is something like this

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So now if another OXP adds Cheese, provided they declare it as "edible", your station will sell it in high quantities at a big discount, but you don't need to know exactly what the baseline price or quantity was set - so if a food-focused OXP was to add "Wine", "Fine Wine" and "Vintage Wine" at a range of prices and quantities, you'd be automatically handling those in reasonable line with a combination of the Wine OXP's basic pricing structure and your station OXP's "food primary source market" style, without necessarily needing to know about every future Wine OXP there might be and explicitly set compatibility.

Note in this example we're still zeroing out all non-food goods - OXP included! - regardless of the local economy. Maybe at this point we'd want to include and document a "hydroponicsoxp-agriculturalequipment" trade good class that other OXPs could use, which this station would buy up at higher demand and prices than normal.

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else if (goodDefinition.classes.indexOf("hydroponicsoxp-agriculturalequipment") >= 0) {
// custom class for other OXPs to add specific agricultural equipment e.g. combine harvesters, compost, fertiliser
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.capacity = 16; // buy a small amount only // TODO: raise capacity if price per tonne is low
goodDefinition.quantity = 0; // not selling this
} else if (goodDefinition.key == "machinery") {
// the basic Oolite Machinery commodity isn't in the custom class but we need to buy something if
// no OXPs adding it are installed
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.quantity = 0; // not selling
goodDefinition.capacity = 16; // small capacity to buy
} else {
// don't buy or sell any other commodity
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So you can see this one has a mix of using, mutating and overruling the definitions set by the system market and OXP commodity definitions ... with this method you could have a whole bunch of OXPs setting up themed stations, and a whole different bunch adding their own custom commodities, and they'd barely have to know about each other to ensure reasonable consistency and compatibility from someone installing any combination of them. (- by [[User:Cim|Cim]], 2023)

Note: this gives examples for 1 commodity at a time, but not how to easily do that for ALL the commodities on ALL the extra stations in a system.

== Using the trade-goods.plist ==
The trade-goods.plist was designed to make commodities simpler, by:
:1) Making it a dictionary rather than an unlabelled array so one could tell which parameter was which
:2) Making the price range for a trade good dependent on more sensible variables, so rather than setting the price range with a bitmask, one set the price and quantity variations dependent on the economy and on random chance.

Compare the v.1.81 trade-goods.plist with a v.1.80 commodities.plist - they were designed to give near-identical market behaviour for the built-in trade goods.

But - that only made it more comprehensible. It didn't really let one do anything particularly different to Elite 84 markets - mostly including the "Rich Industrial -> Poor Agricultural" single spectrum. One can tweak that a bit with peak_export and peak_import to get slightly different shapes (so a good might peak at Poor Industrial rather than Rich Industrial) but it doesn't really give one the option of a third economy type still.

''So how does one introduce a new economic pole, such as a mining industry?''

For that, one needs the scripting support. [[Oolite JavaScript Reference: Market Scripts]]. 
One can quite literally do whatever one likes with the prices that way. One could have every *system* have its own separate economy, which varied over time according to events, what the player had previously traded, ''etc. etc.'' to produce something comparable to Elite Dangerous' economic sim, if that's the route one wanted to go down. Obviously the more complexity one adds the harder it gets to script up, but it's now all possible.

[[File:SOTL Altmap F8.png|thumb|right|200px|SOTL Altmap F8 commodities market]]
[[SOTL Altmap]] does have an example of it, which basically throws out the original Elite-like algorithm of trade-goods.plist and starts over. It goes *way* beyond just adding a third economy, too.

Basically in SOTL every trade good is tagged in the trade-goods.plist with a bunch of classes
''e.g.''
classes = ("sotl-ex-salvage","sotl-im-refining","sotl-quantity-high","sotl-priceband-3","sotl-demand-medium","sotl-supply-medium","sotl-volatility-low");
So that means:
- exported by salvage economies
- imported by refining economies
- high quantity, moderate price, low price volatility

Then the market script uses those classes, rather than the standard pricing variables, to define the economic behaviour.
:So line 69-74ish: get the current economy description, convert that to the format used in the class name
:...line 85-90: check for the import and export classes for that economy and see if it's imported or exported
:...lines 100-120: apply various special conditions, so e.g. the sotl-ims-radiation class checks the planet surface radiation levels (custom property in sysinfo) and if the radiation level is high, imports these goods even if the basic economy isn't interested (e.g. "sotl-ceramics-ind" in the plist)
:...and then it uses those calculations (and a bunch more of the classes) in the rest of the script to set the price and quantity depending on whether it's an import, an export, or neither

That's massive overkill for just adding a third mining economy, but one would need to work on a similar principle.

:1) Tag every commodity with classes for (import|export|none)-(agricultural|industrial|mining) as appropriate
:2) Adjust the economy names (there are a few different ways one could do that) so that the 8 economy IDs were allocated to agricultural, industrial and mining economies
:3) Have a price script which like the SOTL one gets the current economy, looks at the classes list to find out if the commodity is imported or exported or neither, and sets the price and quantity accordingly. One could use the standard price_economic, price_average, price_random properties in the plist to give baseline data to the script if one was not planning to do anything too weird.

{Technically one doesn't need the classes - just have the price script contain a list of goods internally for each economy - but this way if other people add extra trade goods in their own OXPs, they can tag them up for mining economy support too}

All fairly straightforward theoretically.

''The biggest impediment to doing a wholesale reworking of the economic system, is just how incompatible it makes lots and lots of OXP's. In order to override the vanilla commodities as in SOTL, requires setting a script for each in trade-goods.plist. Which is fine if it's the only OXP that wants to play around with commodity prices. As soon as two OXP's try to do the same thing, one gets a conflict and no longer knows which OXP pricing model is in play.''

''For SOTL it's fine, because it uses the scenario system to forcibly eject all other OXP's from use while it's running. But if one wants the OXP to go in the general playing pool set of OXP's, it becomes much more complicated. [[User:Phkb|Phkb]] spent a long time trying to work out why his market script wasn't running, only to find that [[UPS Courier]] was quietly adjusting the markets in certain systems via the planetinfo.plist file. And there are a lot of OXP's that want to play in this space, tweaking prices up or down.''

''Hence one usually abandons using any of the script options, and just tweaks the price after all the scripts have finished playing, ''eg'' in [[Smugglers]]. It was the only way to guarantee getting some sort of bump in a price when wanted.''

== Links ==
*[[Oolite JavaScript Reference: Market Scripts]]
*[[Commodities.plist]] - the precursor (which still mostly works!). If it doesn't see [https://bb.oolite.space/viewtopic.php?p=246145#p246145 here] (2015)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16828 Proposal for 1.82: support for economic changes] ([[User:Cim|Cim]], 2014)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16735 Cim on introducing the Trade-goods.plist and deprecating the commodities.plist] (2014)
{{QuoteText|Text=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.|Source=([https://bb.oolite.space/viewtopic.php?p=226722#p226722 Cim in Progress Thread (2014)])}}
=== Using the Trade-goods.plist ===
*[https://bb.oolite.space/viewtopic.php?f=4&t=20576 How to get the displayName for a commodity in the Main Station Market?] (2020)
*[https://bb.oolite.space/viewtopic.php?f=6&t=17269 Thinking about Planet Income classification] (2015)

{{QuoteText|Text=
In 1.81 this is a lot easier to OXP - you can introduce as many economies as you like, though you are limited to eight economy symbols (so if you wanted lots of economy types, you might end up with Poor Industrial, Avg Industrial and Rich Industrial sharing a symbol on the map). The trade good pricing scripts can then be used to set up different price categories in different economies (and introduce additional trade goods, or split an existing good into multiple categories, which may be necessary if you're adding more economies).

Resetting economies across the planets is a big change in terms of lines of code, but is also very easy to automate. If OXPers are looking for a scripting tool to use for this sort of automation, then NodeJS or io.js is free and also uses Javascript as its language, so you don't need to learn a new one - and may even be able to share code between your build scripts and your OXP, though I haven't tried that yet.|Source=([https://bb.oolite.space/viewtopic.php?f=6&t=17269 Cim in Planet Income thread (2015)])}}

== Preamble ==
To tweak the pricing/availability of commodities in (''eg''.) a station, you need to define the market inside the station's Shipdata.plist - or include a "hook" inside that shipdata.plist to a javascript Oolite Market Script (which allows more complex definitions).

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:

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

== Handlers ==

=== updateGeneralCommodityDefinition ===
{{oolite-method-added|1.81}}
function updateGeneralCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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 = <code>false</code> 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 ===
{{oolite-method-added|1.81}}
function updateLocalCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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.

[https://bb.oolite.space/viewtopic.php?f=4&t=17621#p239979 Here is an example] of how to use this method.

== Links ==

=== Examples ===
*Phkb's update of [[SW_Economy]] (v.3.10) creates new economies for "mining worlds" (hewn out from some low tech poor agricultural worlds) with utterly different price scales for mineral, agricultural & industrial goods, as well as medicine.

''These others will be found at the bottom of the wiki page on the'' [[Trade-goods.plist]].
*Setting an orbital main station's slaves on sale to zero
*Creating an invariant market independent of the local system economy (agricultural/industrial)

Trade-goods (abridged)

2026-06-19T10:17:33Z

Wildeblood: /* Property keys */

'''You are probably looking for [[Trade-goods.plist]]''', rather than this page.

[[File:Distant Riches.png|thumb|right|200px|MORE THAN FIFTY NEW TRADE GOODS]]

== F.A.Q. ==

The goal of this page is to answer the following questions.

=== How many different places can market influences be hiding? ===

In plists, in market scripts, and in station methods in ''any damned script''.

==== Which plists exactly? ====

At least trade-goods.plist , shipdata.plist , shipdata-overides.plist (sp?), planetinfo.plist can set '''market definitions''' directly.

At least trade-goods.plist , shipdata.plist , shipdata-overides.plist (sp?), planetinfo.plist can set links to '''market scripts'''.

==== Which market scripts exactly? ====

See below.

==== What methods might lurk in ''any damned script''? ====

station.setMarketPrice() or
station.setMarketQuantity()

=== How do we define a new "trade-good" (commodity) '''non-bogusly?''' ===

With trade-goods.plist

=== How will sub-standard OXPs thwart us? ===

By careless use of "default" in market influences to destroy things they don't even know exist.

==== Can we move the world-script in AristoShares OXP into a market script? ====

That would prevent deadbeat scripts from interfering with it. Good idea, research required.

=== Can we define new properties for commodities? ===

Where can we set "aita_image" values?

=== Is the economy 0<->7 dipole set in stone? ===

Does it really require javascript to overcome this?

If so, what is the actual function of the peak_import & peak_export properties?

== Preamble ==

The trade-goods.plist file defines "trade goods" (commodities/cargo). But, it does not ''e.g.'' remove slaves from a particular station or make them cost twice as much as they do at the main orbital station. To do such things, ''i.e.'' to tweak the pricing/availability of commodities in a particular station, you need to define the market inside that station, either within its [[Shipdata.plist]] or within a [[Oolite_Market_Scripts|market script]] linked from its shipdata.plist.

== Overview ==

The '''trade-goods.plist''' file is a dictionary of dictionaries, with (canonical) commodity names as keys to dictionaries of key-value pairs 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 (listed thematically, not alphabetically) ==

=== 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 commodity class names. Classes can be used by secondary stations (only secondary markets?) to set pricing rules for groups of commodities.

=== comment ===
A string that will be displayed on the F8 F8 commodity detail screen to describe the commodity. This can be modified later by [[Oolite_JavaScript_Reference:_Manifest#setComment|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 [[Oolite Market Scripts|market script]] for this trade good when calculating main station quantities and prices.

'''Note:''' [https://bb.oolite.space/viewtopic.php?p=235837#p235837 What's the difference between the market script specified in planetinfo.plist and the one called for by trade-goods.plist?] (2015)

=== name ===
A string containing the name of the trade good. This may contain [keys]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 [[Oolite_JavaScript_Reference:_Manifest#setShortComment|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.

=== Discussion of classes ===

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)

== Secondary Market Definitions ==

The primary market is that of the system's main station (''i.e.'' the javascript object system.mainStation.market ) Secondary markets are other markets, which are influenced by the primary market, ''e.g.'' that of a local Rock Hermit, or a visiting liner or another orbital station. Both quantities and prices will be influenced by those of the primary market. Needless to say, the primary market is randomly recalculated each time the system is visited.

Secondary market definitions are entered in the [[shipdata.plist#market_definition|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''':

# The market definition array is searched from top to bottom for the first element matching the trade good
# The market quantity is scaled in proportion to the relative capacities for that good in the two markets.
# 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|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 [[shipdata.plist#market_capacity|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 [[shipdata.plist#market_monitored|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.

=== Links ===
*[https://bb.oolite.space/viewtopic.php?f=2&t=21512 Secondary Market Definitions Defined] (2023)

== 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 for determining markets for new stations.

=== From the vanilla game: Rock Hermits ===
The "market_definition" 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: the Trade-goods.plist updated from the original 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;
};

}
=== A new commodity (from the trade-goods.plist inside "SW Economy") ===
"medicine" = {
"name" = "[commodity-name medicine]";
"classes" = ("oolite-consumer","oolite-medical");
"quantity_unit" = 1;
"peak_export" = 7;
"peak_import" = 0;
"price_average" = 640;
"price_economic" = 0.25;
"price_random" = 0.15;
"quantity_average" = 5;
"quantity_economic" = 1.5;
"quantity_random" = 1.0;
"legality_export" = 0;
"legality_import" = 0;
"trumble_opinion" = 0.50;
"sort_order" = 500;
"comment" = "[oolite-commodity-medicine]";
};

=== Setting an orbital main station's slaves on sale to zero ===
[[User:Phkb|Phkb]] provided this example which requires a ''planetinfo.plist'' & a new ''.js file'' - there are other ways to achieve the same result
==== 1) planetinfo.plist (to invoke the market script) ====
(in the "Config" folder)

{
"0 96" = {market_script = "digebiti_noslaves.js";};
}

==== 2) Market script: digebiti_noslaves.js ====
(in the "Scripts" folder) - note the complex name, which prevents confusion with other snippets of script

"use strict";
this.name = "digebiti_noslaves";
this.author = "Phkb";
this.copyright = "(C) 2022 Phkb";
this.licence = "CC-NC-by-SA 4.0";
this.description = "Removes slaves for sale in Digebiti";
this.version = "1.0";

this.updateLocalCommodityDefinition = function(goodDefinition, station, systemID) {
if (goodDefinition.key == "slaves" && station && station.isMainStation) {
goodDefinition.quantity = 0;
}
return goodDefinition;
}

This method will work, so long as no other OXP changes the market_script property of the Digebiti system in the same way.

=== Creating an invariant market independent of the local system economy (agricultural/industrial) ===
If you just use a market_definition in shipdata.plist for the station, then you're merely setting variations on the primary system market.

If you want the station prices to be independent of (or more loosely tied to) the system it's in, then you need to use a [[Oolite_Market_Scripts|market script]].

So what you'd have is something like this - let's say it's a hydroponics station, so it always sells food and nothing else, regardless of whether the general system economy is industrial or agricultural:

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.key == "food") {
// are we calculating the basic Oolite "food" trade good right now? If yes, set our own static prices
goodDefinition.price = 25; // 2.5 credits
goodDefinition.quantity = 80; // lots of food
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

Now ... the reason that market definitions are preferred to be mutators of the system economy is for two reasons.
1) it means you can avoid the situation where you end up with two adjacent stations with wildly different prices ... but you can of course handle that in other ways too, station positioning, restricted access, ''etc''.
2) it makes it easier to handle OXP trade goods:
- other OXPs might have added more "food" type goods, ''e.g.'' "Meat" or "Cheese"
- you can learn about those and handle them specifically

} else if (goodDefinition.key == "bobsfoodoxp_cheese") {
// set price and quantity here

... but that means a lot of keeping up with what everyone else is doing with custom goods.

The idea was that for your hydroponics station what you might do instead is something like this

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So now if another OXP adds Cheese, provided they declare it as "edible", your station will sell it in high quantities at a big discount, but you don't need to know exactly what the baseline price or quantity was set - so if a food-focused OXP was to add "Wine", "Fine Wine" and "Vintage Wine" at a range of prices and quantities, you'd be automatically handling those in reasonable line with a combination of the Wine OXP's basic pricing structure and your station OXP's "food primary source market" style, without necessarily needing to know about every future Wine OXP there might be and explicitly set compatibility.

Note in this example we're still zeroing out all non-food goods - OXP included! - regardless of the local economy. Maybe at this point we'd want to include and document a "hydroponicsoxp-agriculturalequipment" trade good class that other OXPs could use, which this station would buy up at higher demand and prices than normal.

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else if (goodDefinition.classes.indexOf("hydroponicsoxp-agriculturalequipment") >= 0) {
// custom class for other OXPs to add specific agricultural equipment e.g. combine harvesters, compost, fertiliser
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.capacity = 16; // buy a small amount only // TODO: raise capacity if price per tonne is low
goodDefinition.quantity = 0; // not selling this
} else if (goodDefinition.key == "machinery") {
// the basic Oolite Machinery commodity isn't in the custom class but we need to buy something if
// no OXPs adding it are installed
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.quantity = 0; // not selling
goodDefinition.capacity = 16; // small capacity to buy
} else {
// don't buy or sell any other commodity
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So you can see this one has a mix of using, mutating and overruling the definitions set by the system market and OXP commodity definitions ... with this method you could have a whole bunch of OXPs setting up themed stations, and a whole different bunch adding their own custom commodities, and they'd barely have to know about each other to ensure reasonable consistency and compatibility from someone installing any combination of them. (- by [[User:Cim|Cim]], 2023)

Note: this gives examples for 1 commodity at a time, but not how to easily do that for ALL the commodities on ALL the extra stations in a system.

== Using the trade-goods.plist ==
The trade-goods.plist was designed to make commodities simpler, by:
:1) Making it a dictionary rather than an unlabelled array so one could tell which parameter was which
:2) Making the price range for a trade good dependent on more sensible variables, so rather than setting the price range with a bitmask, one set the price and quantity variations dependent on the economy and on random chance.

Compare the v.1.81 trade-goods.plist with a v.1.80 commodities.plist - they were designed to give near-identical market behaviour for the built-in trade goods.

But - that only made it more comprehensible. It didn't really let one do anything particularly different to Elite 84 markets - mostly including the "Rich Industrial -> Poor Agricultural" single spectrum. One can tweak that a bit with peak_export and peak_import to get slightly different shapes (so a good might peak at Poor Industrial rather than Rich Industrial) but it doesn't really give one the option of a third economy type still.

''So how does one introduce a new economic pole, such as a mining industry?''

For that, one needs the scripting support. [[Oolite JavaScript Reference: Market Scripts]]. 
One can quite literally do whatever one likes with the prices that way. One could have every *system* have its own separate economy, which varied over time according to events, what the player had previously traded, ''etc. etc.'' to produce something comparable to Elite Dangerous' economic sim, if that's the route one wanted to go down. Obviously the more complexity one adds the harder it gets to script up, but it's now all possible.

[[File:SOTL Altmap F8.png|thumb|right|200px|SOTL Altmap F8 commodities market]]
[[SOTL Altmap]] does have an example of it, which basically throws out the original Elite-like algorithm of trade-goods.plist and starts over. It goes *way* beyond just adding a third economy, too.

Basically in SOTL every trade good is tagged in the trade-goods.plist with a bunch of classes
''e.g.''
classes = ("sotl-ex-salvage","sotl-im-refining","sotl-quantity-high","sotl-priceband-3","sotl-demand-medium","sotl-supply-medium","sotl-volatility-low");
So that means:
- exported by salvage economies
- imported by refining economies
- high quantity, moderate price, low price volatility

Then the market script uses those classes, rather than the standard pricing variables, to define the economic behaviour.
:So line 69-74ish: get the current economy description, convert that to the format used in the class name
:...line 85-90: check for the import and export classes for that economy and see if it's imported or exported
:...lines 100-120: apply various special conditions, so e.g. the sotl-ims-radiation class checks the planet surface radiation levels (custom property in sysinfo) and if the radiation level is high, imports these goods even if the basic economy isn't interested (e.g. "sotl-ceramics-ind" in the plist)
:...and then it uses those calculations (and a bunch more of the classes) in the rest of the script to set the price and quantity depending on whether it's an import, an export, or neither

That's massive overkill for just adding a third mining economy, but one would need to work on a similar principle.

:1) Tag every commodity with classes for (import|export|none)-(agricultural|industrial|mining) as appropriate
:2) Adjust the economy names (there are a few different ways one could do that) so that the 8 economy IDs were allocated to agricultural, industrial and mining economies
:3) Have a price script which like the SOTL one gets the current economy, looks at the classes list to find out if the commodity is imported or exported or neither, and sets the price and quantity accordingly. One could use the standard price_economic, price_average, price_random properties in the plist to give baseline data to the script if one was not planning to do anything too weird.

{Technically one doesn't need the classes - just have the price script contain a list of goods internally for each economy - but this way if other people add extra trade goods in their own OXPs, they can tag them up for mining economy support too}

All fairly straightforward theoretically.

''The biggest impediment to doing a wholesale reworking of the economic system, is just how incompatible it makes lots and lots of OXP's. In order to override the vanilla commodities as in SOTL, requires setting a script for each in trade-goods.plist. Which is fine if it's the only OXP that wants to play around with commodity prices. As soon as two OXP's try to do the same thing, one gets a conflict and no longer knows which OXP pricing model is in play.''

''For SOTL it's fine, because it uses the scenario system to forcibly eject all other OXP's from use while it's running. But if one wants the OXP to go in the general playing pool set of OXP's, it becomes much more complicated. [[User:Phkb|Phkb]] spent a long time trying to work out why his market script wasn't running, only to find that [[UPS Courier]] was quietly adjusting the markets in certain systems via the planetinfo.plist file. And there are a lot of OXP's that want to play in this space, tweaking prices up or down.''

''Hence one usually abandons using any of the script options, and just tweaks the price after all the scripts have finished playing, ''eg'' in [[Smugglers]]. It was the only way to guarantee getting some sort of bump in a price when wanted.''

== Links ==
*[[Oolite JavaScript Reference: Market Scripts]]
*[[Commodities.plist]] - the precursor (which still mostly works!). If it doesn't see [https://bb.oolite.space/viewtopic.php?p=246145#p246145 here] (2015)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16828 Proposal for 1.82: support for economic changes] ([[User:Cim|Cim]], 2014)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16735 Cim on introducing the Trade-goods.plist and deprecating the commodities.plist] (2014)
{{QuoteText|Text=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.|Source=([https://bb.oolite.space/viewtopic.php?p=226722#p226722 Cim in Progress Thread (2014)])}}
=== Using the Trade-goods.plist ===
*[https://bb.oolite.space/viewtopic.php?f=4&t=20576 How to get the displayName for a commodity in the Main Station Market?] (2020)
*[https://bb.oolite.space/viewtopic.php?f=6&t=17269 Thinking about Planet Income classification] (2015)

{{QuoteText|Text=
In 1.81 this is a lot easier to OXP - you can introduce as many economies as you like, though you are limited to eight economy symbols (so if you wanted lots of economy types, you might end up with Poor Industrial, Avg Industrial and Rich Industrial sharing a symbol on the map). The trade good pricing scripts can then be used to set up different price categories in different economies (and introduce additional trade goods, or split an existing good into multiple categories, which may be necessary if you're adding more economies).

Resetting economies across the planets is a big change in terms of lines of code, but is also very easy to automate. If OXPers are looking for a scripting tool to use for this sort of automation, then NodeJS or io.js is free and also uses Javascript as its language, so you don't need to learn a new one - and may even be able to share code between your build scripts and your OXP, though I haven't tried that yet.|Source=([https://bb.oolite.space/viewtopic.php?f=6&t=17269 Cim in Planet Income thread (2015)])}}

== Preamble ==
To tweak the pricing/availability of commodities in (''eg''.) a station, you need to define the market inside the station's Shipdata.plist - or include a "hook" inside that shipdata.plist to a javascript Oolite Market Script (which allows more complex definitions).

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:

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

== Handlers ==

=== updateGeneralCommodityDefinition ===
{{oolite-method-added|1.81}}
function updateGeneralCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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 = <code>false</code> 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 ===
{{oolite-method-added|1.81}}
function updateLocalCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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.

[https://bb.oolite.space/viewtopic.php?f=4&t=17621#p239979 Here is an example] of how to use this method.

== Links ==

=== Examples ===
*Phkb's update of [[SW_Economy]] (v.3.10) creates new economies for "mining worlds" (hewn out from some low tech poor agricultural worlds) with utterly different price scales for mineral, agricultural & industrial goods, as well as medicine.

''These others will be found at the bottom of the wiki page on the'' [[Trade-goods.plist]].
*Setting an orbital main station's slaves on sale to zero
*Creating an invariant market independent of the local system economy (agricultural/industrial)

Trade-goods (abridged)

2026-06-19T10:14:50Z

Wildeblood: /* Can we define new properties for commodities */

'''You are probably looking for [[Trade-goods.plist]]''', rather than this page.

[[File:Distant Riches.png|thumb|right|200px|MORE THAN FIFTY NEW TRADE GOODS]]

== F.A.Q. ==

The goal of this page is to answer the following questions.

=== How many different places can market influences be hiding? ===

In plists, in market scripts, and in station methods in ''any damned script''.

==== Which plists exactly? ====

At least trade-goods.plist , shipdata.plist , shipdata-overides.plist (sp?), planetinfo.plist can set '''market definitions''' directly.

At least trade-goods.plist , shipdata.plist , shipdata-overides.plist (sp?), planetinfo.plist can set links to '''market scripts'''.

==== Which market scripts exactly? ====

See below.

==== What methods might lurk in ''any damned script''? ====

station.setMarketPrice() or
station.setMarketQuantity()

=== How do we define a new "trade-good" (commodity) '''non-bogusly?''' ===

With trade-goods.plist

=== How will sub-standard OXPs thwart us? ===

By careless use of "default" in market influences to destroy things they don't even know exist.

==== Can we move the world-script in AristoShares OXP into a market script? ====

That would prevent deadbeat scripts from interfering with it. Good idea, research required.

=== Can we define new properties for commodities? ===

Where can we set "aita_image" values?

=== Is the economy 0<->7 dipole set in stone? ===

Does it really require javascript to overcome this?

If so, what is the actual function of the peak_import & peak_export properties?

== Preamble ==

The trade-goods.plist file defines "trade goods" (commodities/cargo). But, it does not ''e.g.'' remove slaves from a particular station or make them cost twice as much as they do at the main orbital station. To do such things, ''i.e.'' to tweak the pricing/availability of commodities in a particular station, you need to define the market inside that station, either within its [[Shipdata.plist]] or within a [[Oolite_Market_Scripts|market script]] linked from its shipdata.plist.

== Overview ==

The '''trade-goods.plist''' file is a dictionary of dictionaries, with (canonical) commodity names as keys to dictionaries of key-value pairs 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 commodity class names. Classes can be used by secondary stations (only secondary markets?) to set pricing rules for groups of commodities.

=== comment ===
A string that will be displayed on the F8 F8 commodity detail screen to describe the commodity. This can be modified later by [[Oolite_JavaScript_Reference:_Manifest#setComment|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 [[Oolite Market Scripts|market script]] for this trade good when calculating main station quantities and prices.

'''Note:''' [https://bb.oolite.space/viewtopic.php?p=235837#p235837 What's the difference between the market script specified in planetinfo.plist and the one called for by trade-goods.plist?] (2015)

=== name ===
A string containing the name of the trade good. This may contain [keys]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 [[Oolite_JavaScript_Reference:_Manifest#setShortComment|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.

=== Discussion of classes ===

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)

== Secondary Market Definitions ==

The primary market is that of the system's main station (''i.e.'' the javascript object system.mainStation.market ) Secondary markets are other markets, which are influenced by the primary market, ''e.g.'' that of a local Rock Hermit, or a visiting liner or another orbital station. Both quantities and prices will be influenced by those of the primary market. Needless to say, the primary market is randomly recalculated each time the system is visited.

Secondary market definitions are entered in the [[shipdata.plist#market_definition|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''':

# The market definition array is searched from top to bottom for the first element matching the trade good
# The market quantity is scaled in proportion to the relative capacities for that good in the two markets.
# 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|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 [[shipdata.plist#market_capacity|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 [[shipdata.plist#market_monitored|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.

=== Links ===
*[https://bb.oolite.space/viewtopic.php?f=2&t=21512 Secondary Market Definitions Defined] (2023)

== 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 for determining markets for new stations.

=== From the vanilla game: Rock Hermits ===
The "market_definition" 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: the Trade-goods.plist updated from the original 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;
};

}
=== A new commodity (from the trade-goods.plist inside "SW Economy") ===
"medicine" = {
"name" = "[commodity-name medicine]";
"classes" = ("oolite-consumer","oolite-medical");
"quantity_unit" = 1;
"peak_export" = 7;
"peak_import" = 0;
"price_average" = 640;
"price_economic" = 0.25;
"price_random" = 0.15;
"quantity_average" = 5;
"quantity_economic" = 1.5;
"quantity_random" = 1.0;
"legality_export" = 0;
"legality_import" = 0;
"trumble_opinion" = 0.50;
"sort_order" = 500;
"comment" = "[oolite-commodity-medicine]";
};

=== Setting an orbital main station's slaves on sale to zero ===
[[User:Phkb|Phkb]] provided this example which requires a ''planetinfo.plist'' & a new ''.js file'' - there are other ways to achieve the same result
==== 1) planetinfo.plist (to invoke the market script) ====
(in the "Config" folder)

{
"0 96" = {market_script = "digebiti_noslaves.js";};
}

==== 2) Market script: digebiti_noslaves.js ====
(in the "Scripts" folder) - note the complex name, which prevents confusion with other snippets of script

"use strict";
this.name = "digebiti_noslaves";
this.author = "Phkb";
this.copyright = "(C) 2022 Phkb";
this.licence = "CC-NC-by-SA 4.0";
this.description = "Removes slaves for sale in Digebiti";
this.version = "1.0";

this.updateLocalCommodityDefinition = function(goodDefinition, station, systemID) {
if (goodDefinition.key == "slaves" && station && station.isMainStation) {
goodDefinition.quantity = 0;
}
return goodDefinition;
}

This method will work, so long as no other OXP changes the market_script property of the Digebiti system in the same way.

=== Creating an invariant market independent of the local system economy (agricultural/industrial) ===
If you just use a market_definition in shipdata.plist for the station, then you're merely setting variations on the primary system market.

If you want the station prices to be independent of (or more loosely tied to) the system it's in, then you need to use a [[Oolite_Market_Scripts|market script]].

So what you'd have is something like this - let's say it's a hydroponics station, so it always sells food and nothing else, regardless of whether the general system economy is industrial or agricultural:

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.key == "food") {
// are we calculating the basic Oolite "food" trade good right now? If yes, set our own static prices
goodDefinition.price = 25; // 2.5 credits
goodDefinition.quantity = 80; // lots of food
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

Now ... the reason that market definitions are preferred to be mutators of the system economy is for two reasons.
1) it means you can avoid the situation where you end up with two adjacent stations with wildly different prices ... but you can of course handle that in other ways too, station positioning, restricted access, ''etc''.
2) it makes it easier to handle OXP trade goods:
- other OXPs might have added more "food" type goods, ''e.g.'' "Meat" or "Cheese"
- you can learn about those and handle them specifically

} else if (goodDefinition.key == "bobsfoodoxp_cheese") {
// set price and quantity here

... but that means a lot of keeping up with what everyone else is doing with custom goods.

The idea was that for your hydroponics station what you might do instead is something like this

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So now if another OXP adds Cheese, provided they declare it as "edible", your station will sell it in high quantities at a big discount, but you don't need to know exactly what the baseline price or quantity was set - so if a food-focused OXP was to add "Wine", "Fine Wine" and "Vintage Wine" at a range of prices and quantities, you'd be automatically handling those in reasonable line with a combination of the Wine OXP's basic pricing structure and your station OXP's "food primary source market" style, without necessarily needing to know about every future Wine OXP there might be and explicitly set compatibility.

Note in this example we're still zeroing out all non-food goods - OXP included! - regardless of the local economy. Maybe at this point we'd want to include and document a "hydroponicsoxp-agriculturalequipment" trade good class that other OXPs could use, which this station would buy up at higher demand and prices than normal.

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else if (goodDefinition.classes.indexOf("hydroponicsoxp-agriculturalequipment") >= 0) {
// custom class for other OXPs to add specific agricultural equipment e.g. combine harvesters, compost, fertiliser
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.capacity = 16; // buy a small amount only // TODO: raise capacity if price per tonne is low
goodDefinition.quantity = 0; // not selling this
} else if (goodDefinition.key == "machinery") {
// the basic Oolite Machinery commodity isn't in the custom class but we need to buy something if
// no OXPs adding it are installed
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.quantity = 0; // not selling
goodDefinition.capacity = 16; // small capacity to buy
} else {
// don't buy or sell any other commodity
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So you can see this one has a mix of using, mutating and overruling the definitions set by the system market and OXP commodity definitions ... with this method you could have a whole bunch of OXPs setting up themed stations, and a whole different bunch adding their own custom commodities, and they'd barely have to know about each other to ensure reasonable consistency and compatibility from someone installing any combination of them. (- by [[User:Cim|Cim]], 2023)

Note: this gives examples for 1 commodity at a time, but not how to easily do that for ALL the commodities on ALL the extra stations in a system.

== Using the trade-goods.plist ==
The trade-goods.plist was designed to make commodities simpler, by:
:1) Making it a dictionary rather than an unlabelled array so one could tell which parameter was which
:2) Making the price range for a trade good dependent on more sensible variables, so rather than setting the price range with a bitmask, one set the price and quantity variations dependent on the economy and on random chance.

Compare the v.1.81 trade-goods.plist with a v.1.80 commodities.plist - they were designed to give near-identical market behaviour for the built-in trade goods.

But - that only made it more comprehensible. It didn't really let one do anything particularly different to Elite 84 markets - mostly including the "Rich Industrial -> Poor Agricultural" single spectrum. One can tweak that a bit with peak_export and peak_import to get slightly different shapes (so a good might peak at Poor Industrial rather than Rich Industrial) but it doesn't really give one the option of a third economy type still.

''So how does one introduce a new economic pole, such as a mining industry?''

For that, one needs the scripting support. [[Oolite JavaScript Reference: Market Scripts]]. 
One can quite literally do whatever one likes with the prices that way. One could have every *system* have its own separate economy, which varied over time according to events, what the player had previously traded, ''etc. etc.'' to produce something comparable to Elite Dangerous' economic sim, if that's the route one wanted to go down. Obviously the more complexity one adds the harder it gets to script up, but it's now all possible.

[[File:SOTL Altmap F8.png|thumb|right|200px|SOTL Altmap F8 commodities market]]
[[SOTL Altmap]] does have an example of it, which basically throws out the original Elite-like algorithm of trade-goods.plist and starts over. It goes *way* beyond just adding a third economy, too.

Basically in SOTL every trade good is tagged in the trade-goods.plist with a bunch of classes
''e.g.''
classes = ("sotl-ex-salvage","sotl-im-refining","sotl-quantity-high","sotl-priceband-3","sotl-demand-medium","sotl-supply-medium","sotl-volatility-low");
So that means:
- exported by salvage economies
- imported by refining economies
- high quantity, moderate price, low price volatility

Then the market script uses those classes, rather than the standard pricing variables, to define the economic behaviour.
:So line 69-74ish: get the current economy description, convert that to the format used in the class name
:...line 85-90: check for the import and export classes for that economy and see if it's imported or exported
:...lines 100-120: apply various special conditions, so e.g. the sotl-ims-radiation class checks the planet surface radiation levels (custom property in sysinfo) and if the radiation level is high, imports these goods even if the basic economy isn't interested (e.g. "sotl-ceramics-ind" in the plist)
:...and then it uses those calculations (and a bunch more of the classes) in the rest of the script to set the price and quantity depending on whether it's an import, an export, or neither

That's massive overkill for just adding a third mining economy, but one would need to work on a similar principle.

:1) Tag every commodity with classes for (import|export|none)-(agricultural|industrial|mining) as appropriate
:2) Adjust the economy names (there are a few different ways one could do that) so that the 8 economy IDs were allocated to agricultural, industrial and mining economies
:3) Have a price script which like the SOTL one gets the current economy, looks at the classes list to find out if the commodity is imported or exported or neither, and sets the price and quantity accordingly. One could use the standard price_economic, price_average, price_random properties in the plist to give baseline data to the script if one was not planning to do anything too weird.

{Technically one doesn't need the classes - just have the price script contain a list of goods internally for each economy - but this way if other people add extra trade goods in their own OXPs, they can tag them up for mining economy support too}

All fairly straightforward theoretically.

''The biggest impediment to doing a wholesale reworking of the economic system, is just how incompatible it makes lots and lots of OXP's. In order to override the vanilla commodities as in SOTL, requires setting a script for each in trade-goods.plist. Which is fine if it's the only OXP that wants to play around with commodity prices. As soon as two OXP's try to do the same thing, one gets a conflict and no longer knows which OXP pricing model is in play.''

''For SOTL it's fine, because it uses the scenario system to forcibly eject all other OXP's from use while it's running. But if one wants the OXP to go in the general playing pool set of OXP's, it becomes much more complicated. [[User:Phkb|Phkb]] spent a long time trying to work out why his market script wasn't running, only to find that [[UPS Courier]] was quietly adjusting the markets in certain systems via the planetinfo.plist file. And there are a lot of OXP's that want to play in this space, tweaking prices up or down.''

''Hence one usually abandons using any of the script options, and just tweaks the price after all the scripts have finished playing, ''eg'' in [[Smugglers]]. It was the only way to guarantee getting some sort of bump in a price when wanted.''

== Links ==
*[[Oolite JavaScript Reference: Market Scripts]]
*[[Commodities.plist]] - the precursor (which still mostly works!). If it doesn't see [https://bb.oolite.space/viewtopic.php?p=246145#p246145 here] (2015)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16828 Proposal for 1.82: support for economic changes] ([[User:Cim|Cim]], 2014)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16735 Cim on introducing the Trade-goods.plist and deprecating the commodities.plist] (2014)
{{QuoteText|Text=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.|Source=([https://bb.oolite.space/viewtopic.php?p=226722#p226722 Cim in Progress Thread (2014)])}}
=== Using the Trade-goods.plist ===
*[https://bb.oolite.space/viewtopic.php?f=4&t=20576 How to get the displayName for a commodity in the Main Station Market?] (2020)
*[https://bb.oolite.space/viewtopic.php?f=6&t=17269 Thinking about Planet Income classification] (2015)

{{QuoteText|Text=
In 1.81 this is a lot easier to OXP - you can introduce as many economies as you like, though you are limited to eight economy symbols (so if you wanted lots of economy types, you might end up with Poor Industrial, Avg Industrial and Rich Industrial sharing a symbol on the map). The trade good pricing scripts can then be used to set up different price categories in different economies (and introduce additional trade goods, or split an existing good into multiple categories, which may be necessary if you're adding more economies).

Resetting economies across the planets is a big change in terms of lines of code, but is also very easy to automate. If OXPers are looking for a scripting tool to use for this sort of automation, then NodeJS or io.js is free and also uses Javascript as its language, so you don't need to learn a new one - and may even be able to share code between your build scripts and your OXP, though I haven't tried that yet.|Source=([https://bb.oolite.space/viewtopic.php?f=6&t=17269 Cim in Planet Income thread (2015)])}}

== Preamble ==
To tweak the pricing/availability of commodities in (''eg''.) a station, you need to define the market inside the station's Shipdata.plist - or include a "hook" inside that shipdata.plist to a javascript Oolite Market Script (which allows more complex definitions).

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:

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

== Handlers ==

=== updateGeneralCommodityDefinition ===
{{oolite-method-added|1.81}}
function updateGeneralCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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 = <code>false</code> 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 ===
{{oolite-method-added|1.81}}
function updateLocalCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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.

[https://bb.oolite.space/viewtopic.php?f=4&t=17621#p239979 Here is an example] of how to use this method.

== Links ==

=== Examples ===
*Phkb's update of [[SW_Economy]] (v.3.10) creates new economies for "mining worlds" (hewn out from some low tech poor agricultural worlds) with utterly different price scales for mineral, agricultural & industrial goods, as well as medicine.

''These others will be found at the bottom of the wiki page on the'' [[Trade-goods.plist]].
*Setting an orbital main station's slaves on sale to zero
*Creating an invariant market independent of the local system economy (agricultural/industrial)

Trade-goods (abridged)

2026-06-19T09:40:51Z

Wildeblood: /* How will sub-standard OXPs thwart us? */

'''You are probably looking for [[Trade-goods.plist]]''', rather than this page.

[[File:Distant Riches.png|thumb|right|200px|MORE THAN FIFTY NEW TRADE GOODS]]

== F.A.Q. ==

The goal of this page is to answer the following questions.

=== How many different places can market influences be hiding? ===

In plists, in market scripts, and in station methods in ''any damned script''.

==== Which plists exactly? ====

At least trade-goods.plist , shipdata.plist , shipdata-overides.plist (sp?), planetinfo.plist can set '''market definitions''' directly.

At least trade-goods.plist , shipdata.plist , shipdata-overides.plist (sp?), planetinfo.plist can set links to '''market scripts'''.

==== Which market scripts exactly? ====

See below.

==== What methods might lurk in ''any damned script''? ====

station.setMarketPrice() or
station.setMarketQuantity()

=== How do we define a new "trade-good" (commodity) '''non-bogusly?''' ===

With trade-goods.plist

=== How will sub-standard OXPs thwart us? ===

By careless use of "default" in market influences to destroy things they don't even know exist.

==== Can we move the world-script in AristoShares OXP into a market script? ====

That would prevent deadbeat scripts from interfering with it. Good idea, research required.

=== Can we define new properties for commodities ===

Where can we set "aita_image" values?

== Preamble ==

The trade-goods.plist file defines "trade goods" (commodities/cargo). But, it does not ''e.g.'' remove slaves from a particular station or make them cost twice as much as they do at the main orbital station. To do such things, ''i.e.'' to tweak the pricing/availability of commodities in a particular station, you need to define the market inside that station, either within its [[Shipdata.plist]] or within a [[Oolite_Market_Scripts|market script]] linked from its shipdata.plist.

== Overview ==

The '''trade-goods.plist''' file is a dictionary of dictionaries, with (canonical) commodity names as keys to dictionaries of key-value pairs 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 commodity class names. Classes can be used by secondary stations (only secondary markets?) to set pricing rules for groups of commodities.

=== comment ===
A string that will be displayed on the F8 F8 commodity detail screen to describe the commodity. This can be modified later by [[Oolite_JavaScript_Reference:_Manifest#setComment|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 [[Oolite Market Scripts|market script]] for this trade good when calculating main station quantities and prices.

'''Note:''' [https://bb.oolite.space/viewtopic.php?p=235837#p235837 What's the difference between the market script specified in planetinfo.plist and the one called for by trade-goods.plist?] (2015)

=== name ===
A string containing the name of the trade good. This may contain [keys]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 [[Oolite_JavaScript_Reference:_Manifest#setShortComment|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.

=== Discussion of classes ===

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)

== Secondary Market Definitions ==

The primary market is that of the system's main station (''i.e.'' the javascript object system.mainStation.market ) Secondary markets are other markets, which are influenced by the primary market, ''e.g.'' that of a local Rock Hermit, or a visiting liner or another orbital station. Both quantities and prices will be influenced by those of the primary market. Needless to say, the primary market is randomly recalculated each time the system is visited.

Secondary market definitions are entered in the [[shipdata.plist#market_definition|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''':

# The market definition array is searched from top to bottom for the first element matching the trade good
# The market quantity is scaled in proportion to the relative capacities for that good in the two markets.
# 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|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 [[shipdata.plist#market_capacity|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 [[shipdata.plist#market_monitored|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.

=== Links ===
*[https://bb.oolite.space/viewtopic.php?f=2&t=21512 Secondary Market Definitions Defined] (2023)

== 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 for determining markets for new stations.

=== From the vanilla game: Rock Hermits ===
The "market_definition" 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: the Trade-goods.plist updated from the original 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;
};

}
=== A new commodity (from the trade-goods.plist inside "SW Economy") ===
"medicine" = {
"name" = "[commodity-name medicine]";
"classes" = ("oolite-consumer","oolite-medical");
"quantity_unit" = 1;
"peak_export" = 7;
"peak_import" = 0;
"price_average" = 640;
"price_economic" = 0.25;
"price_random" = 0.15;
"quantity_average" = 5;
"quantity_economic" = 1.5;
"quantity_random" = 1.0;
"legality_export" = 0;
"legality_import" = 0;
"trumble_opinion" = 0.50;
"sort_order" = 500;
"comment" = "[oolite-commodity-medicine]";
};

=== Setting an orbital main station's slaves on sale to zero ===
[[User:Phkb|Phkb]] provided this example which requires a ''planetinfo.plist'' & a new ''.js file'' - there are other ways to achieve the same result
==== 1) planetinfo.plist (to invoke the market script) ====
(in the "Config" folder)

{
"0 96" = {market_script = "digebiti_noslaves.js";};
}

==== 2) Market script: digebiti_noslaves.js ====
(in the "Scripts" folder) - note the complex name, which prevents confusion with other snippets of script

"use strict";
this.name = "digebiti_noslaves";
this.author = "Phkb";
this.copyright = "(C) 2022 Phkb";
this.licence = "CC-NC-by-SA 4.0";
this.description = "Removes slaves for sale in Digebiti";
this.version = "1.0";

this.updateLocalCommodityDefinition = function(goodDefinition, station, systemID) {
if (goodDefinition.key == "slaves" && station && station.isMainStation) {
goodDefinition.quantity = 0;
}
return goodDefinition;
}

This method will work, so long as no other OXP changes the market_script property of the Digebiti system in the same way.

=== Creating an invariant market independent of the local system economy (agricultural/industrial) ===
If you just use a market_definition in shipdata.plist for the station, then you're merely setting variations on the primary system market.

If you want the station prices to be independent of (or more loosely tied to) the system it's in, then you need to use a [[Oolite_Market_Scripts|market script]].

So what you'd have is something like this - let's say it's a hydroponics station, so it always sells food and nothing else, regardless of whether the general system economy is industrial or agricultural:

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.key == "food") {
// are we calculating the basic Oolite "food" trade good right now? If yes, set our own static prices
goodDefinition.price = 25; // 2.5 credits
goodDefinition.quantity = 80; // lots of food
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

Now ... the reason that market definitions are preferred to be mutators of the system economy is for two reasons.
1) it means you can avoid the situation where you end up with two adjacent stations with wildly different prices ... but you can of course handle that in other ways too, station positioning, restricted access, ''etc''.
2) it makes it easier to handle OXP trade goods:
- other OXPs might have added more "food" type goods, ''e.g.'' "Meat" or "Cheese"
- you can learn about those and handle them specifically

} else if (goodDefinition.key == "bobsfoodoxp_cheese") {
// set price and quantity here

... but that means a lot of keeping up with what everyone else is doing with custom goods.

The idea was that for your hydroponics station what you might do instead is something like this

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So now if another OXP adds Cheese, provided they declare it as "edible", your station will sell it in high quantities at a big discount, but you don't need to know exactly what the baseline price or quantity was set - so if a food-focused OXP was to add "Wine", "Fine Wine" and "Vintage Wine" at a range of prices and quantities, you'd be automatically handling those in reasonable line with a combination of the Wine OXP's basic pricing structure and your station OXP's "food primary source market" style, without necessarily needing to know about every future Wine OXP there might be and explicitly set compatibility.

Note in this example we're still zeroing out all non-food goods - OXP included! - regardless of the local economy. Maybe at this point we'd want to include and document a "hydroponicsoxp-agriculturalequipment" trade good class that other OXPs could use, which this station would buy up at higher demand and prices than normal.

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else if (goodDefinition.classes.indexOf("hydroponicsoxp-agriculturalequipment") >= 0) {
// custom class for other OXPs to add specific agricultural equipment e.g. combine harvesters, compost, fertiliser
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.capacity = 16; // buy a small amount only // TODO: raise capacity if price per tonne is low
goodDefinition.quantity = 0; // not selling this
} else if (goodDefinition.key == "machinery") {
// the basic Oolite Machinery commodity isn't in the custom class but we need to buy something if
// no OXPs adding it are installed
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.quantity = 0; // not selling
goodDefinition.capacity = 16; // small capacity to buy
} else {
// don't buy or sell any other commodity
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So you can see this one has a mix of using, mutating and overruling the definitions set by the system market and OXP commodity definitions ... with this method you could have a whole bunch of OXPs setting up themed stations, and a whole different bunch adding their own custom commodities, and they'd barely have to know about each other to ensure reasonable consistency and compatibility from someone installing any combination of them. (- by [[User:Cim|Cim]], 2023)

Note: this gives examples for 1 commodity at a time, but not how to easily do that for ALL the commodities on ALL the extra stations in a system.

== Using the trade-goods.plist ==
The trade-goods.plist was designed to make commodities simpler, by:
:1) Making it a dictionary rather than an unlabelled array so one could tell which parameter was which
:2) Making the price range for a trade good dependent on more sensible variables, so rather than setting the price range with a bitmask, one set the price and quantity variations dependent on the economy and on random chance.

Compare the v.1.81 trade-goods.plist with a v.1.80 commodities.plist - they were designed to give near-identical market behaviour for the built-in trade goods.

But - that only made it more comprehensible. It didn't really let one do anything particularly different to Elite 84 markets - mostly including the "Rich Industrial -> Poor Agricultural" single spectrum. One can tweak that a bit with peak_export and peak_import to get slightly different shapes (so a good might peak at Poor Industrial rather than Rich Industrial) but it doesn't really give one the option of a third economy type still.

''So how does one introduce a new economic pole, such as a mining industry?''

For that, one needs the scripting support. [[Oolite JavaScript Reference: Market Scripts]]. 
One can quite literally do whatever one likes with the prices that way. One could have every *system* have its own separate economy, which varied over time according to events, what the player had previously traded, ''etc. etc.'' to produce something comparable to Elite Dangerous' economic sim, if that's the route one wanted to go down. Obviously the more complexity one adds the harder it gets to script up, but it's now all possible.

[[File:SOTL Altmap F8.png|thumb|right|200px|SOTL Altmap F8 commodities market]]
[[SOTL Altmap]] does have an example of it, which basically throws out the original Elite-like algorithm of trade-goods.plist and starts over. It goes *way* beyond just adding a third economy, too.

Basically in SOTL every trade good is tagged in the trade-goods.plist with a bunch of classes
''e.g.''
classes = ("sotl-ex-salvage","sotl-im-refining","sotl-quantity-high","sotl-priceband-3","sotl-demand-medium","sotl-supply-medium","sotl-volatility-low");
So that means:
- exported by salvage economies
- imported by refining economies
- high quantity, moderate price, low price volatility

Then the market script uses those classes, rather than the standard pricing variables, to define the economic behaviour.
:So line 69-74ish: get the current economy description, convert that to the format used in the class name
:...line 85-90: check for the import and export classes for that economy and see if it's imported or exported
:...lines 100-120: apply various special conditions, so e.g. the sotl-ims-radiation class checks the planet surface radiation levels (custom property in sysinfo) and if the radiation level is high, imports these goods even if the basic economy isn't interested (e.g. "sotl-ceramics-ind" in the plist)
:...and then it uses those calculations (and a bunch more of the classes) in the rest of the script to set the price and quantity depending on whether it's an import, an export, or neither

That's massive overkill for just adding a third mining economy, but one would need to work on a similar principle.

:1) Tag every commodity with classes for (import|export|none)-(agricultural|industrial|mining) as appropriate
:2) Adjust the economy names (there are a few different ways one could do that) so that the 8 economy IDs were allocated to agricultural, industrial and mining economies
:3) Have a price script which like the SOTL one gets the current economy, looks at the classes list to find out if the commodity is imported or exported or neither, and sets the price and quantity accordingly. One could use the standard price_economic, price_average, price_random properties in the plist to give baseline data to the script if one was not planning to do anything too weird.

{Technically one doesn't need the classes - just have the price script contain a list of goods internally for each economy - but this way if other people add extra trade goods in their own OXPs, they can tag them up for mining economy support too}

All fairly straightforward theoretically.

''The biggest impediment to doing a wholesale reworking of the economic system, is just how incompatible it makes lots and lots of OXP's. In order to override the vanilla commodities as in SOTL, requires setting a script for each in trade-goods.plist. Which is fine if it's the only OXP that wants to play around with commodity prices. As soon as two OXP's try to do the same thing, one gets a conflict and no longer knows which OXP pricing model is in play.''

''For SOTL it's fine, because it uses the scenario system to forcibly eject all other OXP's from use while it's running. But if one wants the OXP to go in the general playing pool set of OXP's, it becomes much more complicated. [[User:Phkb|Phkb]] spent a long time trying to work out why his market script wasn't running, only to find that [[UPS Courier]] was quietly adjusting the markets in certain systems via the planetinfo.plist file. And there are a lot of OXP's that want to play in this space, tweaking prices up or down.''

''Hence one usually abandons using any of the script options, and just tweaks the price after all the scripts have finished playing, ''eg'' in [[Smugglers]]. It was the only way to guarantee getting some sort of bump in a price when wanted.''

== Links ==
*[[Oolite JavaScript Reference: Market Scripts]]
*[[Commodities.plist]] - the precursor (which still mostly works!). If it doesn't see [https://bb.oolite.space/viewtopic.php?p=246145#p246145 here] (2015)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16828 Proposal for 1.82: support for economic changes] ([[User:Cim|Cim]], 2014)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16735 Cim on introducing the Trade-goods.plist and deprecating the commodities.plist] (2014)
{{QuoteText|Text=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.|Source=([https://bb.oolite.space/viewtopic.php?p=226722#p226722 Cim in Progress Thread (2014)])}}
=== Using the Trade-goods.plist ===
*[https://bb.oolite.space/viewtopic.php?f=4&t=20576 How to get the displayName for a commodity in the Main Station Market?] (2020)
*[https://bb.oolite.space/viewtopic.php?f=6&t=17269 Thinking about Planet Income classification] (2015)

{{QuoteText|Text=
In 1.81 this is a lot easier to OXP - you can introduce as many economies as you like, though you are limited to eight economy symbols (so if you wanted lots of economy types, you might end up with Poor Industrial, Avg Industrial and Rich Industrial sharing a symbol on the map). The trade good pricing scripts can then be used to set up different price categories in different economies (and introduce additional trade goods, or split an existing good into multiple categories, which may be necessary if you're adding more economies).

Resetting economies across the planets is a big change in terms of lines of code, but is also very easy to automate. If OXPers are looking for a scripting tool to use for this sort of automation, then NodeJS or io.js is free and also uses Javascript as its language, so you don't need to learn a new one - and may even be able to share code between your build scripts and your OXP, though I haven't tried that yet.|Source=([https://bb.oolite.space/viewtopic.php?f=6&t=17269 Cim in Planet Income thread (2015)])}}

== Preamble ==
To tweak the pricing/availability of commodities in (''eg''.) a station, you need to define the market inside the station's Shipdata.plist - or include a "hook" inside that shipdata.plist to a javascript Oolite Market Script (which allows more complex definitions).

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:

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

== Handlers ==

=== updateGeneralCommodityDefinition ===
{{oolite-method-added|1.81}}
function updateGeneralCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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 = <code>false</code> 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 ===
{{oolite-method-added|1.81}}
function updateLocalCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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.

[https://bb.oolite.space/viewtopic.php?f=4&t=17621#p239979 Here is an example] of how to use this method.

== Links ==

=== Examples ===
*Phkb's update of [[SW_Economy]] (v.3.10) creates new economies for "mining worlds" (hewn out from some low tech poor agricultural worlds) with utterly different price scales for mineral, agricultural & industrial goods, as well as medicine.

''These others will be found at the bottom of the wiki page on the'' [[Trade-goods.plist]].
*Setting an orbital main station's slaves on sale to zero
*Creating an invariant market independent of the local system economy (agricultural/industrial)

Trade-goods (abridged)

2026-06-19T09:32:56Z

Wildeblood: /* How will sub-standard OXPs thwart us? */

'''You are probably looking for [[Trade-goods.plist]]''', rather than this page.

[[File:Distant Riches.png|thumb|right|200px|MORE THAN FIFTY NEW TRADE GOODS]]

== F.A.Q. ==

The goal of this page is to answer the following questions.

=== How many different places can market influences be hiding? ===

In plists, in market scripts, and in station methods in ''any damned script''.

==== Which plists exactly? ====

At least trade-goods.plist , shipdata.plist , shipdata-overides.plist (sp?), planetinfo.plist can set '''market definitions''' directly.

At least trade-goods.plist , shipdata.plist , shipdata-overides.plist (sp?), planetinfo.plist can set links to '''market scripts'''.

==== Which market scripts exactly? ====

See below.

==== What methods might lurk in ''any damned script''? ====

station.setMarketPrice() or
station.setMarketQuantity()

=== How do we define a new "trade-good" (commodity) '''non-bogusly?''' ===

With trade-goods.plist

=== How will sub-standard OXPs thwart us? ===

By careless use of "default" in market influences to destroy things they don't even know exist.

==== Can we move the world-script in AristoShares OXP into a market script? ====

That would prevent deadbeat scripts from interfering with it. Good idea, research required.

== Preamble ==

The trade-goods.plist file defines "trade goods" (commodities/cargo). But, it does not ''e.g.'' remove slaves from a particular station or make them cost twice as much as they do at the main orbital station. To do such things, ''i.e.'' to tweak the pricing/availability of commodities in a particular station, you need to define the market inside that station, either within its [[Shipdata.plist]] or within a [[Oolite_Market_Scripts|market script]] linked from its shipdata.plist.

== Overview ==

The '''trade-goods.plist''' file is a dictionary of dictionaries, with (canonical) commodity names as keys to dictionaries of key-value pairs 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 commodity class names. Classes can be used by secondary stations (only secondary markets?) to set pricing rules for groups of commodities.

=== comment ===
A string that will be displayed on the F8 F8 commodity detail screen to describe the commodity. This can be modified later by [[Oolite_JavaScript_Reference:_Manifest#setComment|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 [[Oolite Market Scripts|market script]] for this trade good when calculating main station quantities and prices.

'''Note:''' [https://bb.oolite.space/viewtopic.php?p=235837#p235837 What's the difference between the market script specified in planetinfo.plist and the one called for by trade-goods.plist?] (2015)

=== name ===
A string containing the name of the trade good. This may contain [keys]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 [[Oolite_JavaScript_Reference:_Manifest#setShortComment|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.

=== Discussion of classes ===

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)

== Secondary Market Definitions ==

The primary market is that of the system's main station (''i.e.'' the javascript object system.mainStation.market ) Secondary markets are other markets, which are influenced by the primary market, ''e.g.'' that of a local Rock Hermit, or a visiting liner or another orbital station. Both quantities and prices will be influenced by those of the primary market. Needless to say, the primary market is randomly recalculated each time the system is visited.

Secondary market definitions are entered in the [[shipdata.plist#market_definition|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''':

# The market definition array is searched from top to bottom for the first element matching the trade good
# The market quantity is scaled in proportion to the relative capacities for that good in the two markets.
# 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|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 [[shipdata.plist#market_capacity|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 [[shipdata.plist#market_monitored|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.

=== Links ===
*[https://bb.oolite.space/viewtopic.php?f=2&t=21512 Secondary Market Definitions Defined] (2023)

== 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 for determining markets for new stations.

=== From the vanilla game: Rock Hermits ===
The "market_definition" 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: the Trade-goods.plist updated from the original 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;
};

}
=== A new commodity (from the trade-goods.plist inside "SW Economy") ===
"medicine" = {
"name" = "[commodity-name medicine]";
"classes" = ("oolite-consumer","oolite-medical");
"quantity_unit" = 1;
"peak_export" = 7;
"peak_import" = 0;
"price_average" = 640;
"price_economic" = 0.25;
"price_random" = 0.15;
"quantity_average" = 5;
"quantity_economic" = 1.5;
"quantity_random" = 1.0;
"legality_export" = 0;
"legality_import" = 0;
"trumble_opinion" = 0.50;
"sort_order" = 500;
"comment" = "[oolite-commodity-medicine]";
};

=== Setting an orbital main station's slaves on sale to zero ===
[[User:Phkb|Phkb]] provided this example which requires a ''planetinfo.plist'' & a new ''.js file'' - there are other ways to achieve the same result
==== 1) planetinfo.plist (to invoke the market script) ====
(in the "Config" folder)

{
"0 96" = {market_script = "digebiti_noslaves.js";};
}

==== 2) Market script: digebiti_noslaves.js ====
(in the "Scripts" folder) - note the complex name, which prevents confusion with other snippets of script

"use strict";
this.name = "digebiti_noslaves";
this.author = "Phkb";
this.copyright = "(C) 2022 Phkb";
this.licence = "CC-NC-by-SA 4.0";
this.description = "Removes slaves for sale in Digebiti";
this.version = "1.0";

this.updateLocalCommodityDefinition = function(goodDefinition, station, systemID) {
if (goodDefinition.key == "slaves" && station && station.isMainStation) {
goodDefinition.quantity = 0;
}
return goodDefinition;
}

This method will work, so long as no other OXP changes the market_script property of the Digebiti system in the same way.

=== Creating an invariant market independent of the local system economy (agricultural/industrial) ===
If you just use a market_definition in shipdata.plist for the station, then you're merely setting variations on the primary system market.

If you want the station prices to be independent of (or more loosely tied to) the system it's in, then you need to use a [[Oolite_Market_Scripts|market script]].

So what you'd have is something like this - let's say it's a hydroponics station, so it always sells food and nothing else, regardless of whether the general system economy is industrial or agricultural:

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.key == "food") {
// are we calculating the basic Oolite "food" trade good right now? If yes, set our own static prices
goodDefinition.price = 25; // 2.5 credits
goodDefinition.quantity = 80; // lots of food
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

Now ... the reason that market definitions are preferred to be mutators of the system economy is for two reasons.
1) it means you can avoid the situation where you end up with two adjacent stations with wildly different prices ... but you can of course handle that in other ways too, station positioning, restricted access, ''etc''.
2) it makes it easier to handle OXP trade goods:
- other OXPs might have added more "food" type goods, ''e.g.'' "Meat" or "Cheese"
- you can learn about those and handle them specifically

} else if (goodDefinition.key == "bobsfoodoxp_cheese") {
// set price and quantity here

... but that means a lot of keeping up with what everyone else is doing with custom goods.

The idea was that for your hydroponics station what you might do instead is something like this

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So now if another OXP adds Cheese, provided they declare it as "edible", your station will sell it in high quantities at a big discount, but you don't need to know exactly what the baseline price or quantity was set - so if a food-focused OXP was to add "Wine", "Fine Wine" and "Vintage Wine" at a range of prices and quantities, you'd be automatically handling those in reasonable line with a combination of the Wine OXP's basic pricing structure and your station OXP's "food primary source market" style, without necessarily needing to know about every future Wine OXP there might be and explicitly set compatibility.

Note in this example we're still zeroing out all non-food goods - OXP included! - regardless of the local economy. Maybe at this point we'd want to include and document a "hydroponicsoxp-agriculturalequipment" trade good class that other OXPs could use, which this station would buy up at higher demand and prices than normal.

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else if (goodDefinition.classes.indexOf("hydroponicsoxp-agriculturalequipment") >= 0) {
// custom class for other OXPs to add specific agricultural equipment e.g. combine harvesters, compost, fertiliser
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.capacity = 16; // buy a small amount only // TODO: raise capacity if price per tonne is low
goodDefinition.quantity = 0; // not selling this
} else if (goodDefinition.key == "machinery") {
// the basic Oolite Machinery commodity isn't in the custom class but we need to buy something if
// no OXPs adding it are installed
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.quantity = 0; // not selling
goodDefinition.capacity = 16; // small capacity to buy
} else {
// don't buy or sell any other commodity
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So you can see this one has a mix of using, mutating and overruling the definitions set by the system market and OXP commodity definitions ... with this method you could have a whole bunch of OXPs setting up themed stations, and a whole different bunch adding their own custom commodities, and they'd barely have to know about each other to ensure reasonable consistency and compatibility from someone installing any combination of them. (- by [[User:Cim|Cim]], 2023)

Note: this gives examples for 1 commodity at a time, but not how to easily do that for ALL the commodities on ALL the extra stations in a system.

== Using the trade-goods.plist ==
The trade-goods.plist was designed to make commodities simpler, by:
:1) Making it a dictionary rather than an unlabelled array so one could tell which parameter was which
:2) Making the price range for a trade good dependent on more sensible variables, so rather than setting the price range with a bitmask, one set the price and quantity variations dependent on the economy and on random chance.

Compare the v.1.81 trade-goods.plist with a v.1.80 commodities.plist - they were designed to give near-identical market behaviour for the built-in trade goods.

But - that only made it more comprehensible. It didn't really let one do anything particularly different to Elite 84 markets - mostly including the "Rich Industrial -> Poor Agricultural" single spectrum. One can tweak that a bit with peak_export and peak_import to get slightly different shapes (so a good might peak at Poor Industrial rather than Rich Industrial) but it doesn't really give one the option of a third economy type still.

''So how does one introduce a new economic pole, such as a mining industry?''

For that, one needs the scripting support. [[Oolite JavaScript Reference: Market Scripts]]. 
One can quite literally do whatever one likes with the prices that way. One could have every *system* have its own separate economy, which varied over time according to events, what the player had previously traded, ''etc. etc.'' to produce something comparable to Elite Dangerous' economic sim, if that's the route one wanted to go down. Obviously the more complexity one adds the harder it gets to script up, but it's now all possible.

[[File:SOTL Altmap F8.png|thumb|right|200px|SOTL Altmap F8 commodities market]]
[[SOTL Altmap]] does have an example of it, which basically throws out the original Elite-like algorithm of trade-goods.plist and starts over. It goes *way* beyond just adding a third economy, too.

Basically in SOTL every trade good is tagged in the trade-goods.plist with a bunch of classes
''e.g.''
classes = ("sotl-ex-salvage","sotl-im-refining","sotl-quantity-high","sotl-priceband-3","sotl-demand-medium","sotl-supply-medium","sotl-volatility-low");
So that means:
- exported by salvage economies
- imported by refining economies
- high quantity, moderate price, low price volatility

Then the market script uses those classes, rather than the standard pricing variables, to define the economic behaviour.
:So line 69-74ish: get the current economy description, convert that to the format used in the class name
:...line 85-90: check for the import and export classes for that economy and see if it's imported or exported
:...lines 100-120: apply various special conditions, so e.g. the sotl-ims-radiation class checks the planet surface radiation levels (custom property in sysinfo) and if the radiation level is high, imports these goods even if the basic economy isn't interested (e.g. "sotl-ceramics-ind" in the plist)
:...and then it uses those calculations (and a bunch more of the classes) in the rest of the script to set the price and quantity depending on whether it's an import, an export, or neither

That's massive overkill for just adding a third mining economy, but one would need to work on a similar principle.

:1) Tag every commodity with classes for (import|export|none)-(agricultural|industrial|mining) as appropriate
:2) Adjust the economy names (there are a few different ways one could do that) so that the 8 economy IDs were allocated to agricultural, industrial and mining economies
:3) Have a price script which like the SOTL one gets the current economy, looks at the classes list to find out if the commodity is imported or exported or neither, and sets the price and quantity accordingly. One could use the standard price_economic, price_average, price_random properties in the plist to give baseline data to the script if one was not planning to do anything too weird.

{Technically one doesn't need the classes - just have the price script contain a list of goods internally for each economy - but this way if other people add extra trade goods in their own OXPs, they can tag them up for mining economy support too}

All fairly straightforward theoretically.

''The biggest impediment to doing a wholesale reworking of the economic system, is just how incompatible it makes lots and lots of OXP's. In order to override the vanilla commodities as in SOTL, requires setting a script for each in trade-goods.plist. Which is fine if it's the only OXP that wants to play around with commodity prices. As soon as two OXP's try to do the same thing, one gets a conflict and no longer knows which OXP pricing model is in play.''

''For SOTL it's fine, because it uses the scenario system to forcibly eject all other OXP's from use while it's running. But if one wants the OXP to go in the general playing pool set of OXP's, it becomes much more complicated. [[User:Phkb|Phkb]] spent a long time trying to work out why his market script wasn't running, only to find that [[UPS Courier]] was quietly adjusting the markets in certain systems via the planetinfo.plist file. And there are a lot of OXP's that want to play in this space, tweaking prices up or down.''

''Hence one usually abandons using any of the script options, and just tweaks the price after all the scripts have finished playing, ''eg'' in [[Smugglers]]. It was the only way to guarantee getting some sort of bump in a price when wanted.''

== Links ==
*[[Oolite JavaScript Reference: Market Scripts]]
*[[Commodities.plist]] - the precursor (which still mostly works!). If it doesn't see [https://bb.oolite.space/viewtopic.php?p=246145#p246145 here] (2015)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16828 Proposal for 1.82: support for economic changes] ([[User:Cim|Cim]], 2014)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16735 Cim on introducing the Trade-goods.plist and deprecating the commodities.plist] (2014)
{{QuoteText|Text=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.|Source=([https://bb.oolite.space/viewtopic.php?p=226722#p226722 Cim in Progress Thread (2014)])}}
=== Using the Trade-goods.plist ===
*[https://bb.oolite.space/viewtopic.php?f=4&t=20576 How to get the displayName for a commodity in the Main Station Market?] (2020)
*[https://bb.oolite.space/viewtopic.php?f=6&t=17269 Thinking about Planet Income classification] (2015)

{{QuoteText|Text=
In 1.81 this is a lot easier to OXP - you can introduce as many economies as you like, though you are limited to eight economy symbols (so if you wanted lots of economy types, you might end up with Poor Industrial, Avg Industrial and Rich Industrial sharing a symbol on the map). The trade good pricing scripts can then be used to set up different price categories in different economies (and introduce additional trade goods, or split an existing good into multiple categories, which may be necessary if you're adding more economies).

Resetting economies across the planets is a big change in terms of lines of code, but is also very easy to automate. If OXPers are looking for a scripting tool to use for this sort of automation, then NodeJS or io.js is free and also uses Javascript as its language, so you don't need to learn a new one - and may even be able to share code between your build scripts and your OXP, though I haven't tried that yet.|Source=([https://bb.oolite.space/viewtopic.php?f=6&t=17269 Cim in Planet Income thread (2015)])}}

== Preamble ==
To tweak the pricing/availability of commodities in (''eg''.) a station, you need to define the market inside the station's Shipdata.plist - or include a "hook" inside that shipdata.plist to a javascript Oolite Market Script (which allows more complex definitions).

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:

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

== Handlers ==

=== updateGeneralCommodityDefinition ===
{{oolite-method-added|1.81}}
function updateGeneralCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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 = <code>false</code> 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 ===
{{oolite-method-added|1.81}}
function updateLocalCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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.

[https://bb.oolite.space/viewtopic.php?f=4&t=17621#p239979 Here is an example] of how to use this method.

== Links ==

=== Examples ===
*Phkb's update of [[SW_Economy]] (v.3.10) creates new economies for "mining worlds" (hewn out from some low tech poor agricultural worlds) with utterly different price scales for mineral, agricultural & industrial goods, as well as medicine.

''These others will be found at the bottom of the wiki page on the'' [[Trade-goods.plist]].
*Setting an orbital main station's slaves on sale to zero
*Creating an invariant market independent of the local system economy (agricultural/industrial)

Trade-goods (abridged)

2026-06-19T09:26:06Z

Wildeblood:

'''You are probably looking for [[Trade-goods.plist]]''', rather than this page.

[[File:Distant Riches.png|thumb|right|200px|MORE THAN FIFTY NEW TRADE GOODS]]

== F.A.Q. ==

The goal of this page is to answer the following questions.

=== How many different places can market influences be hiding? ===

In plists, in market scripts, and in station methods in ''any damned script''.

==== Which plists exactly? ====

At least trade-goods.plist , shipdata.plist , shipdata-overides.plist (sp?), planetinfo.plist can set '''market definitions''' directly.

At least trade-goods.plist , shipdata.plist , shipdata-overides.plist (sp?), planetinfo.plist can set links to '''market scripts'''.

==== Which market scripts exactly? ====

See below.

==== What methods might lurk in ''any damned script''? ====

station.setMarketPrice() or
station.setMarketQuantity()

=== How do we define a new "trade-good" (commodity) '''non-bogusly?''' ===

With trade-goods.plist

=== How will sub-standard OXPs thwart us? ===

By careless use of "default" in market influences to destroy things they don't even know exist.

== Preamble ==

The trade-goods.plist file defines "trade goods" (commodities/cargo). But, it does not ''e.g.'' remove slaves from a particular station or make them cost twice as much as they do at the main orbital station. To do such things, ''i.e.'' to tweak the pricing/availability of commodities in a particular station, you need to define the market inside that station, either within its [[Shipdata.plist]] or within a [[Oolite_Market_Scripts|market script]] linked from its shipdata.plist.

== Overview ==

The '''trade-goods.plist''' file is a dictionary of dictionaries, with (canonical) commodity names as keys to dictionaries of key-value pairs 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 commodity class names. Classes can be used by secondary stations (only secondary markets?) to set pricing rules for groups of commodities.

=== comment ===
A string that will be displayed on the F8 F8 commodity detail screen to describe the commodity. This can be modified later by [[Oolite_JavaScript_Reference:_Manifest#setComment|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 [[Oolite Market Scripts|market script]] for this trade good when calculating main station quantities and prices.

'''Note:''' [https://bb.oolite.space/viewtopic.php?p=235837#p235837 What's the difference between the market script specified in planetinfo.plist and the one called for by trade-goods.plist?] (2015)

=== name ===
A string containing the name of the trade good. This may contain [keys]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 [[Oolite_JavaScript_Reference:_Manifest#setShortComment|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.

=== Discussion of classes ===

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)

== Secondary Market Definitions ==

The primary market is that of the system's main station (''i.e.'' the javascript object system.mainStation.market ) Secondary markets are other markets, which are influenced by the primary market, ''e.g.'' that of a local Rock Hermit, or a visiting liner or another orbital station. Both quantities and prices will be influenced by those of the primary market. Needless to say, the primary market is randomly recalculated each time the system is visited.

Secondary market definitions are entered in the [[shipdata.plist#market_definition|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''':

# The market definition array is searched from top to bottom for the first element matching the trade good
# The market quantity is scaled in proportion to the relative capacities for that good in the two markets.
# 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|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 [[shipdata.plist#market_capacity|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 [[shipdata.plist#market_monitored|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.

=== Links ===
*[https://bb.oolite.space/viewtopic.php?f=2&t=21512 Secondary Market Definitions Defined] (2023)

== 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 for determining markets for new stations.

=== From the vanilla game: Rock Hermits ===
The "market_definition" 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: the Trade-goods.plist updated from the original 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;
};

}
=== A new commodity (from the trade-goods.plist inside "SW Economy") ===
"medicine" = {
"name" = "[commodity-name medicine]";
"classes" = ("oolite-consumer","oolite-medical");
"quantity_unit" = 1;
"peak_export" = 7;
"peak_import" = 0;
"price_average" = 640;
"price_economic" = 0.25;
"price_random" = 0.15;
"quantity_average" = 5;
"quantity_economic" = 1.5;
"quantity_random" = 1.0;
"legality_export" = 0;
"legality_import" = 0;
"trumble_opinion" = 0.50;
"sort_order" = 500;
"comment" = "[oolite-commodity-medicine]";
};

=== Setting an orbital main station's slaves on sale to zero ===
[[User:Phkb|Phkb]] provided this example which requires a ''planetinfo.plist'' & a new ''.js file'' - there are other ways to achieve the same result
==== 1) planetinfo.plist (to invoke the market script) ====
(in the "Config" folder)

{
"0 96" = {market_script = "digebiti_noslaves.js";};
}

==== 2) Market script: digebiti_noslaves.js ====
(in the "Scripts" folder) - note the complex name, which prevents confusion with other snippets of script

"use strict";
this.name = "digebiti_noslaves";
this.author = "Phkb";
this.copyright = "(C) 2022 Phkb";
this.licence = "CC-NC-by-SA 4.0";
this.description = "Removes slaves for sale in Digebiti";
this.version = "1.0";

this.updateLocalCommodityDefinition = function(goodDefinition, station, systemID) {
if (goodDefinition.key == "slaves" && station && station.isMainStation) {
goodDefinition.quantity = 0;
}
return goodDefinition;
}

This method will work, so long as no other OXP changes the market_script property of the Digebiti system in the same way.

=== Creating an invariant market independent of the local system economy (agricultural/industrial) ===
If you just use a market_definition in shipdata.plist for the station, then you're merely setting variations on the primary system market.

If you want the station prices to be independent of (or more loosely tied to) the system it's in, then you need to use a [[Oolite_Market_Scripts|market script]].

So what you'd have is something like this - let's say it's a hydroponics station, so it always sells food and nothing else, regardless of whether the general system economy is industrial or agricultural:

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.key == "food") {
// are we calculating the basic Oolite "food" trade good right now? If yes, set our own static prices
goodDefinition.price = 25; // 2.5 credits
goodDefinition.quantity = 80; // lots of food
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

Now ... the reason that market definitions are preferred to be mutators of the system economy is for two reasons.
1) it means you can avoid the situation where you end up with two adjacent stations with wildly different prices ... but you can of course handle that in other ways too, station positioning, restricted access, ''etc''.
2) it makes it easier to handle OXP trade goods:
- other OXPs might have added more "food" type goods, ''e.g.'' "Meat" or "Cheese"
- you can learn about those and handle them specifically

} else if (goodDefinition.key == "bobsfoodoxp_cheese") {
// set price and quantity here

... but that means a lot of keeping up with what everyone else is doing with custom goods.

The idea was that for your hydroponics station what you might do instead is something like this

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So now if another OXP adds Cheese, provided they declare it as "edible", your station will sell it in high quantities at a big discount, but you don't need to know exactly what the baseline price or quantity was set - so if a food-focused OXP was to add "Wine", "Fine Wine" and "Vintage Wine" at a range of prices and quantities, you'd be automatically handling those in reasonable line with a combination of the Wine OXP's basic pricing structure and your station OXP's "food primary source market" style, without necessarily needing to know about every future Wine OXP there might be and explicitly set compatibility.

Note in this example we're still zeroing out all non-food goods - OXP included! - regardless of the local economy. Maybe at this point we'd want to include and document a "hydroponicsoxp-agriculturalequipment" trade good class that other OXPs could use, which this station would buy up at higher demand and prices than normal.

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else if (goodDefinition.classes.indexOf("hydroponicsoxp-agriculturalequipment") >= 0) {
// custom class for other OXPs to add specific agricultural equipment e.g. combine harvesters, compost, fertiliser
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.capacity = 16; // buy a small amount only // TODO: raise capacity if price per tonne is low
goodDefinition.quantity = 0; // not selling this
} else if (goodDefinition.key == "machinery") {
// the basic Oolite Machinery commodity isn't in the custom class but we need to buy something if
// no OXPs adding it are installed
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.quantity = 0; // not selling
goodDefinition.capacity = 16; // small capacity to buy
} else {
// don't buy or sell any other commodity
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So you can see this one has a mix of using, mutating and overruling the definitions set by the system market and OXP commodity definitions ... with this method you could have a whole bunch of OXPs setting up themed stations, and a whole different bunch adding their own custom commodities, and they'd barely have to know about each other to ensure reasonable consistency and compatibility from someone installing any combination of them. (- by [[User:Cim|Cim]], 2023)

Note: this gives examples for 1 commodity at a time, but not how to easily do that for ALL the commodities on ALL the extra stations in a system.

== Using the trade-goods.plist ==
The trade-goods.plist was designed to make commodities simpler, by:
:1) Making it a dictionary rather than an unlabelled array so one could tell which parameter was which
:2) Making the price range for a trade good dependent on more sensible variables, so rather than setting the price range with a bitmask, one set the price and quantity variations dependent on the economy and on random chance.

Compare the v.1.81 trade-goods.plist with a v.1.80 commodities.plist - they were designed to give near-identical market behaviour for the built-in trade goods.

But - that only made it more comprehensible. It didn't really let one do anything particularly different to Elite 84 markets - mostly including the "Rich Industrial -> Poor Agricultural" single spectrum. One can tweak that a bit with peak_export and peak_import to get slightly different shapes (so a good might peak at Poor Industrial rather than Rich Industrial) but it doesn't really give one the option of a third economy type still.

''So how does one introduce a new economic pole, such as a mining industry?''

For that, one needs the scripting support. [[Oolite JavaScript Reference: Market Scripts]]. 
One can quite literally do whatever one likes with the prices that way. One could have every *system* have its own separate economy, which varied over time according to events, what the player had previously traded, ''etc. etc.'' to produce something comparable to Elite Dangerous' economic sim, if that's the route one wanted to go down. Obviously the more complexity one adds the harder it gets to script up, but it's now all possible.

[[File:SOTL Altmap F8.png|thumb|right|200px|SOTL Altmap F8 commodities market]]
[[SOTL Altmap]] does have an example of it, which basically throws out the original Elite-like algorithm of trade-goods.plist and starts over. It goes *way* beyond just adding a third economy, too.

Basically in SOTL every trade good is tagged in the trade-goods.plist with a bunch of classes
''e.g.''
classes = ("sotl-ex-salvage","sotl-im-refining","sotl-quantity-high","sotl-priceband-3","sotl-demand-medium","sotl-supply-medium","sotl-volatility-low");
So that means:
- exported by salvage economies
- imported by refining economies
- high quantity, moderate price, low price volatility

Then the market script uses those classes, rather than the standard pricing variables, to define the economic behaviour.
:So line 69-74ish: get the current economy description, convert that to the format used in the class name
:...line 85-90: check for the import and export classes for that economy and see if it's imported or exported
:...lines 100-120: apply various special conditions, so e.g. the sotl-ims-radiation class checks the planet surface radiation levels (custom property in sysinfo) and if the radiation level is high, imports these goods even if the basic economy isn't interested (e.g. "sotl-ceramics-ind" in the plist)
:...and then it uses those calculations (and a bunch more of the classes) in the rest of the script to set the price and quantity depending on whether it's an import, an export, or neither

That's massive overkill for just adding a third mining economy, but one would need to work on a similar principle.

:1) Tag every commodity with classes for (import|export|none)-(agricultural|industrial|mining) as appropriate
:2) Adjust the economy names (there are a few different ways one could do that) so that the 8 economy IDs were allocated to agricultural, industrial and mining economies
:3) Have a price script which like the SOTL one gets the current economy, looks at the classes list to find out if the commodity is imported or exported or neither, and sets the price and quantity accordingly. One could use the standard price_economic, price_average, price_random properties in the plist to give baseline data to the script if one was not planning to do anything too weird.

{Technically one doesn't need the classes - just have the price script contain a list of goods internally for each economy - but this way if other people add extra trade goods in their own OXPs, they can tag them up for mining economy support too}

All fairly straightforward theoretically.

''The biggest impediment to doing a wholesale reworking of the economic system, is just how incompatible it makes lots and lots of OXP's. In order to override the vanilla commodities as in SOTL, requires setting a script for each in trade-goods.plist. Which is fine if it's the only OXP that wants to play around with commodity prices. As soon as two OXP's try to do the same thing, one gets a conflict and no longer knows which OXP pricing model is in play.''

''For SOTL it's fine, because it uses the scenario system to forcibly eject all other OXP's from use while it's running. But if one wants the OXP to go in the general playing pool set of OXP's, it becomes much more complicated. [[User:Phkb|Phkb]] spent a long time trying to work out why his market script wasn't running, only to find that [[UPS Courier]] was quietly adjusting the markets in certain systems via the planetinfo.plist file. And there are a lot of OXP's that want to play in this space, tweaking prices up or down.''

''Hence one usually abandons using any of the script options, and just tweaks the price after all the scripts have finished playing, ''eg'' in [[Smugglers]]. It was the only way to guarantee getting some sort of bump in a price when wanted.''

== Links ==
*[[Oolite JavaScript Reference: Market Scripts]]
*[[Commodities.plist]] - the precursor (which still mostly works!). If it doesn't see [https://bb.oolite.space/viewtopic.php?p=246145#p246145 here] (2015)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16828 Proposal for 1.82: support for economic changes] ([[User:Cim|Cim]], 2014)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16735 Cim on introducing the Trade-goods.plist and deprecating the commodities.plist] (2014)
{{QuoteText|Text=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.|Source=([https://bb.oolite.space/viewtopic.php?p=226722#p226722 Cim in Progress Thread (2014)])}}
=== Using the Trade-goods.plist ===
*[https://bb.oolite.space/viewtopic.php?f=4&t=20576 How to get the displayName for a commodity in the Main Station Market?] (2020)
*[https://bb.oolite.space/viewtopic.php?f=6&t=17269 Thinking about Planet Income classification] (2015)

{{QuoteText|Text=
In 1.81 this is a lot easier to OXP - you can introduce as many economies as you like, though you are limited to eight economy symbols (so if you wanted lots of economy types, you might end up with Poor Industrial, Avg Industrial and Rich Industrial sharing a symbol on the map). The trade good pricing scripts can then be used to set up different price categories in different economies (and introduce additional trade goods, or split an existing good into multiple categories, which may be necessary if you're adding more economies).

Resetting economies across the planets is a big change in terms of lines of code, but is also very easy to automate. If OXPers are looking for a scripting tool to use for this sort of automation, then NodeJS or io.js is free and also uses Javascript as its language, so you don't need to learn a new one - and may even be able to share code between your build scripts and your OXP, though I haven't tried that yet.|Source=([https://bb.oolite.space/viewtopic.php?f=6&t=17269 Cim in Planet Income thread (2015)])}}

== Preamble ==
To tweak the pricing/availability of commodities in (''eg''.) a station, you need to define the market inside the station's Shipdata.plist - or include a "hook" inside that shipdata.plist to a javascript Oolite Market Script (which allows more complex definitions).

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:

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

== Handlers ==

=== updateGeneralCommodityDefinition ===
{{oolite-method-added|1.81}}
function updateGeneralCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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 = <code>false</code> 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 ===
{{oolite-method-added|1.81}}
function updateLocalCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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.

[https://bb.oolite.space/viewtopic.php?f=4&t=17621#p239979 Here is an example] of how to use this method.

== Links ==

=== Examples ===
*Phkb's update of [[SW_Economy]] (v.3.10) creates new economies for "mining worlds" (hewn out from some low tech poor agricultural worlds) with utterly different price scales for mineral, agricultural & industrial goods, as well as medicine.

''These others will be found at the bottom of the wiki page on the'' [[Trade-goods.plist]].
*Setting an orbital main station's slaves on sale to zero
*Creating an invariant market independent of the local system economy (agricultural/industrial)

Trade-goods (abridged)

2026-06-19T09:08:41Z

Wildeblood: /* F.A.Q. */

'''You are probably looking for [[Trade-goods.plist]]''', rather than this page.

== F.A.Q. ==

The goal of this page is to answer the following questions.

=== How many different places can market influences be hiding? ===

In plists, in market scripts, and in station methods in ''any damned script''.

==== Which plists exactly? ====

At least trade-goods.plist , shipdata.plist , shipdata-overides.plist (sp?), planetinfo.plist can set '''market definitions''' directly.

At least trade-goods.plist , shipdata.plist , shipdata-overides.plist (sp?), planetinfo.plist can set links to '''market scripts'''.

==== Which market scripts exactly? ====

See below.

==== What methods might lurk in ''any damned script''? ====

station.setMarketPrice() or
station.setMarketQuantity()

=== How do we define a new "trade-good" (commodity) '''non-bogusly?''' ===

With trade-goods.plist

=== How will sub-standard OXPs thwart us? ===

By careless use of "default" in market influences to destroy things they don't even know exist.

== Preamble ==

The trade-goods.plist file defines "trade goods" (commodities/cargo). But, it does not ''e.g.'' remove slaves from a particular station or make them cost twice as much as they do at the main orbital station. To do such things, ''i.e.'' to tweak the pricing/availability of commodities in a particular station, you need to define the market inside that station, either within its [[Shipdata.plist]] or within a [[Oolite_Market_Scripts|market script]] linked from its shipdata.plist.

== Overview ==

The '''trade-goods.plist''' file is a dictionary of dictionaries, with (canonical) commodity names as keys to dictionaries of key-value pairs 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 commodity class names. Classes can be used by secondary stations (only secondary markets?) to set pricing rules for groups of commodities.

=== comment ===
A string that will be displayed on the F8 F8 commodity detail screen to describe the commodity. This can be modified later by [[Oolite_JavaScript_Reference:_Manifest#setComment|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 [[Oolite Market Scripts|market script]] for this trade good when calculating main station quantities and prices.

'''Note:''' [https://bb.oolite.space/viewtopic.php?p=235837#p235837 What's the difference between the market script specified in planetinfo.plist and the one called for by trade-goods.plist?] (2015)

=== name ===
A string containing the name of the trade good. This may contain [keys]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 [[Oolite_JavaScript_Reference:_Manifest#setShortComment|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.

=== Discussion of classes ===

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)

== Secondary Market Definitions ==

The primary market is that of the system's main station (''i.e.'' the javascript object system.mainStation.market ) Secondary markets are other markets, which are influenced by the primary market, ''e.g.'' that of a local Rock Hermit, or a visiting liner or another orbital station. Both quantities and prices will be influenced by those of the primary market. Needless to say, the primary market is randomly recalculated each time the system is visited.

Secondary market definitions are entered in the [[shipdata.plist#market_definition|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''':

# The market definition array is searched from top to bottom for the first element matching the trade good
# The market quantity is scaled in proportion to the relative capacities for that good in the two markets.
# 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|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 [[shipdata.plist#market_capacity|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 [[shipdata.plist#market_monitored|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.

=== Links ===
*[https://bb.oolite.space/viewtopic.php?f=2&t=21512 Secondary Market Definitions Defined] (2023)

== 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 for determining markets for new stations.

=== From the vanilla game: Rock Hermits ===
The "market_definition" 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: the Trade-goods.plist updated from the original 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;
};

}
=== A new commodity (from the trade-goods.plist inside "SW Economy") ===
"medicine" = {
"name" = "[commodity-name medicine]";
"classes" = ("oolite-consumer","oolite-medical");
"quantity_unit" = 1;
"peak_export" = 7;
"peak_import" = 0;
"price_average" = 640;
"price_economic" = 0.25;
"price_random" = 0.15;
"quantity_average" = 5;
"quantity_economic" = 1.5;
"quantity_random" = 1.0;
"legality_export" = 0;
"legality_import" = 0;
"trumble_opinion" = 0.50;
"sort_order" = 500;
"comment" = "[oolite-commodity-medicine]";
};

=== Setting an orbital main station's slaves on sale to zero ===
[[User:Phkb|Phkb]] provided this example which requires a ''planetinfo.plist'' & a new ''.js file'' - there are other ways to achieve the same result
==== 1) planetinfo.plist (to invoke the market script) ====
(in the "Config" folder)

{
"0 96" = {market_script = "digebiti_noslaves.js";};
}

==== 2) Market script: digebiti_noslaves.js ====
(in the "Scripts" folder) - note the complex name, which prevents confusion with other snippets of script

"use strict";
this.name = "digebiti_noslaves";
this.author = "Phkb";
this.copyright = "(C) 2022 Phkb";
this.licence = "CC-NC-by-SA 4.0";
this.description = "Removes slaves for sale in Digebiti";
this.version = "1.0";

this.updateLocalCommodityDefinition = function(goodDefinition, station, systemID) {
if (goodDefinition.key == "slaves" && station && station.isMainStation) {
goodDefinition.quantity = 0;
}
return goodDefinition;
}

This method will work, so long as no other OXP changes the market_script property of the Digebiti system in the same way.

=== Creating an invariant market independent of the local system economy (agricultural/industrial) ===
If you just use a market_definition in shipdata.plist for the station, then you're merely setting variations on the primary system market.

If you want the station prices to be independent of (or more loosely tied to) the system it's in, then you need to use a [[Oolite_Market_Scripts|market script]].

So what you'd have is something like this - let's say it's a hydroponics station, so it always sells food and nothing else, regardless of whether the general system economy is industrial or agricultural:

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.key == "food") {
// are we calculating the basic Oolite "food" trade good right now? If yes, set our own static prices
goodDefinition.price = 25; // 2.5 credits
goodDefinition.quantity = 80; // lots of food
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

Now ... the reason that market definitions are preferred to be mutators of the system economy is for two reasons.
1) it means you can avoid the situation where you end up with two adjacent stations with wildly different prices ... but you can of course handle that in other ways too, station positioning, restricted access, ''etc''.
2) it makes it easier to handle OXP trade goods:
- other OXPs might have added more "food" type goods, ''e.g.'' "Meat" or "Cheese"
- you can learn about those and handle them specifically

} else if (goodDefinition.key == "bobsfoodoxp_cheese") {
// set price and quantity here

... but that means a lot of keeping up with what everyone else is doing with custom goods.

The idea was that for your hydroponics station what you might do instead is something like this

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So now if another OXP adds Cheese, provided they declare it as "edible", your station will sell it in high quantities at a big discount, but you don't need to know exactly what the baseline price or quantity was set - so if a food-focused OXP was to add "Wine", "Fine Wine" and "Vintage Wine" at a range of prices and quantities, you'd be automatically handling those in reasonable line with a combination of the Wine OXP's basic pricing structure and your station OXP's "food primary source market" style, without necessarily needing to know about every future Wine OXP there might be and explicitly set compatibility.

Note in this example we're still zeroing out all non-food goods - OXP included! - regardless of the local economy. Maybe at this point we'd want to include and document a "hydroponicsoxp-agriculturalequipment" trade good class that other OXPs could use, which this station would buy up at higher demand and prices than normal.

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else if (goodDefinition.classes.indexOf("hydroponicsoxp-agriculturalequipment") >= 0) {
// custom class for other OXPs to add specific agricultural equipment e.g. combine harvesters, compost, fertiliser
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.capacity = 16; // buy a small amount only // TODO: raise capacity if price per tonne is low
goodDefinition.quantity = 0; // not selling this
} else if (goodDefinition.key == "machinery") {
// the basic Oolite Machinery commodity isn't in the custom class but we need to buy something if
// no OXPs adding it are installed
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.quantity = 0; // not selling
goodDefinition.capacity = 16; // small capacity to buy
} else {
// don't buy or sell any other commodity
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So you can see this one has a mix of using, mutating and overruling the definitions set by the system market and OXP commodity definitions ... with this method you could have a whole bunch of OXPs setting up themed stations, and a whole different bunch adding their own custom commodities, and they'd barely have to know about each other to ensure reasonable consistency and compatibility from someone installing any combination of them. (- by [[User:Cim|Cim]], 2023)

Note: this gives examples for 1 commodity at a time, but not how to easily do that for ALL the commodities on ALL the extra stations in a system.

== Using the trade-goods.plist ==
The trade-goods.plist was designed to make commodities simpler, by:
:1) Making it a dictionary rather than an unlabelled array so one could tell which parameter was which
:2) Making the price range for a trade good dependent on more sensible variables, so rather than setting the price range with a bitmask, one set the price and quantity variations dependent on the economy and on random chance.

Compare the v.1.81 trade-goods.plist with a v.1.80 commodities.plist - they were designed to give near-identical market behaviour for the built-in trade goods.

But - that only made it more comprehensible. It didn't really let one do anything particularly different to Elite 84 markets - mostly including the "Rich Industrial -> Poor Agricultural" single spectrum. One can tweak that a bit with peak_export and peak_import to get slightly different shapes (so a good might peak at Poor Industrial rather than Rich Industrial) but it doesn't really give one the option of a third economy type still.

''So how does one introduce a new economic pole, such as a mining industry?''

For that, one needs the scripting support. [[Oolite JavaScript Reference: Market Scripts]]. 
One can quite literally do whatever one likes with the prices that way. One could have every *system* have its own separate economy, which varied over time according to events, what the player had previously traded, ''etc. etc.'' to produce something comparable to Elite Dangerous' economic sim, if that's the route one wanted to go down. Obviously the more complexity one adds the harder it gets to script up, but it's now all possible.

[[File:SOTL Altmap F8.png|thumb|right|200px|SOTL Altmap F8 commodities market]]
[[SOTL Altmap]] does have an example of it, which basically throws out the original Elite-like algorithm of trade-goods.plist and starts over. It goes *way* beyond just adding a third economy, too.

Basically in SOTL every trade good is tagged in the trade-goods.plist with a bunch of classes
''e.g.''
classes = ("sotl-ex-salvage","sotl-im-refining","sotl-quantity-high","sotl-priceband-3","sotl-demand-medium","sotl-supply-medium","sotl-volatility-low");
So that means:
- exported by salvage economies
- imported by refining economies
- high quantity, moderate price, low price volatility

Then the market script uses those classes, rather than the standard pricing variables, to define the economic behaviour.
:So line 69-74ish: get the current economy description, convert that to the format used in the class name
:...line 85-90: check for the import and export classes for that economy and see if it's imported or exported
:...lines 100-120: apply various special conditions, so e.g. the sotl-ims-radiation class checks the planet surface radiation levels (custom property in sysinfo) and if the radiation level is high, imports these goods even if the basic economy isn't interested (e.g. "sotl-ceramics-ind" in the plist)
:...and then it uses those calculations (and a bunch more of the classes) in the rest of the script to set the price and quantity depending on whether it's an import, an export, or neither

That's massive overkill for just adding a third mining economy, but one would need to work on a similar principle.

:1) Tag every commodity with classes for (import|export|none)-(agricultural|industrial|mining) as appropriate
:2) Adjust the economy names (there are a few different ways one could do that) so that the 8 economy IDs were allocated to agricultural, industrial and mining economies
:3) Have a price script which like the SOTL one gets the current economy, looks at the classes list to find out if the commodity is imported or exported or neither, and sets the price and quantity accordingly. One could use the standard price_economic, price_average, price_random properties in the plist to give baseline data to the script if one was not planning to do anything too weird.

{Technically one doesn't need the classes - just have the price script contain a list of goods internally for each economy - but this way if other people add extra trade goods in their own OXPs, they can tag them up for mining economy support too}

All fairly straightforward theoretically.

''The biggest impediment to doing a wholesale reworking of the economic system, is just how incompatible it makes lots and lots of OXP's. In order to override the vanilla commodities as in SOTL, requires setting a script for each in trade-goods.plist. Which is fine if it's the only OXP that wants to play around with commodity prices. As soon as two OXP's try to do the same thing, one gets a conflict and no longer knows which OXP pricing model is in play.''

''For SOTL it's fine, because it uses the scenario system to forcibly eject all other OXP's from use while it's running. But if one wants the OXP to go in the general playing pool set of OXP's, it becomes much more complicated. [[User:Phkb|Phkb]] spent a long time trying to work out why his market script wasn't running, only to find that [[UPS Courier]] was quietly adjusting the markets in certain systems via the planetinfo.plist file. And there are a lot of OXP's that want to play in this space, tweaking prices up or down.''

''Hence one usually abandons using any of the script options, and just tweaks the price after all the scripts have finished playing, ''eg'' in [[Smugglers]]. It was the only way to guarantee getting some sort of bump in a price when wanted.''

== Links ==
*[[Oolite JavaScript Reference: Market Scripts]]
*[[Commodities.plist]] - the precursor (which still mostly works!). If it doesn't see [https://bb.oolite.space/viewtopic.php?p=246145#p246145 here] (2015)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16828 Proposal for 1.82: support for economic changes] ([[User:Cim|Cim]], 2014)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16735 Cim on introducing the Trade-goods.plist and deprecating the commodities.plist] (2014)
{{QuoteText|Text=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.|Source=([https://bb.oolite.space/viewtopic.php?p=226722#p226722 Cim in Progress Thread (2014)])}}
=== Using the Trade-goods.plist ===
*[https://bb.oolite.space/viewtopic.php?f=4&t=20576 How to get the displayName for a commodity in the Main Station Market?] (2020)
*[https://bb.oolite.space/viewtopic.php?f=6&t=17269 Thinking about Planet Income classification] (2015)

{{QuoteText|Text=
In 1.81 this is a lot easier to OXP - you can introduce as many economies as you like, though you are limited to eight economy symbols (so if you wanted lots of economy types, you might end up with Poor Industrial, Avg Industrial and Rich Industrial sharing a symbol on the map). The trade good pricing scripts can then be used to set up different price categories in different economies (and introduce additional trade goods, or split an existing good into multiple categories, which may be necessary if you're adding more economies).

Resetting economies across the planets is a big change in terms of lines of code, but is also very easy to automate. If OXPers are looking for a scripting tool to use for this sort of automation, then NodeJS or io.js is free and also uses Javascript as its language, so you don't need to learn a new one - and may even be able to share code between your build scripts and your OXP, though I haven't tried that yet.|Source=([https://bb.oolite.space/viewtopic.php?f=6&t=17269 Cim in Planet Income thread (2015)])}}

== Preamble ==
To tweak the pricing/availability of commodities in (''eg''.) a station, you need to define the market inside the station's Shipdata.plist - or include a "hook" inside that shipdata.plist to a javascript Oolite Market Script (which allows more complex definitions).

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:

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

== Handlers ==

=== updateGeneralCommodityDefinition ===
{{oolite-method-added|1.81}}
function updateGeneralCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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 = <code>false</code> 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 ===
{{oolite-method-added|1.81}}
function updateLocalCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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.

[https://bb.oolite.space/viewtopic.php?f=4&t=17621#p239979 Here is an example] of how to use this method.

== Links ==

=== Examples ===
*Phkb's update of [[SW_Economy]] (v.3.10) creates new economies for "mining worlds" (hewn out from some low tech poor agricultural worlds) with utterly different price scales for mineral, agricultural & industrial goods, as well as medicine.

''These others will be found at the bottom of the wiki page on the'' [[Trade-goods.plist]].
*Setting an orbital main station's slaves on sale to zero
*Creating an invariant market independent of the local system economy (agricultural/industrial)

Trade-goods (abridged)

2026-06-19T08:48:53Z

Wildeblood: /* classes */

'''You are probably looking for [[Trade-goods.plist]]''', rather than this page.

== F.A.Q. ==

The goal of this page is to answer the following questions.

=== How many different places can market influences be hiding? ===

In plists, in market scripts, and in station methods in ''any damned script''.

2. Which plists exactly?

At least trade-goods.plist , shipdata.plist , shipdata-overides.plist (sp?), planetinfo.plist

3. Which market scripts exactly?

4. What methods?

== Preamble ==

The trade-goods.plist file defines "trade goods" (commodities/cargo). But, it does not ''e.g.'' remove slaves from a particular station or make them cost twice as much as they do at the main orbital station. To do such things, ''i.e.'' to tweak the pricing/availability of commodities in a particular station, you need to define the market inside that station, either within its [[Shipdata.plist]] or within a [[Oolite_Market_Scripts|market script]] linked from its shipdata.plist.

== Overview ==

The '''trade-goods.plist''' file is a dictionary of dictionaries, with (canonical) commodity names as keys to dictionaries of key-value pairs 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 commodity class names. Classes can be used by secondary stations (only secondary markets?) to set pricing rules for groups of commodities.

=== comment ===
A string that will be displayed on the F8 F8 commodity detail screen to describe the commodity. This can be modified later by [[Oolite_JavaScript_Reference:_Manifest#setComment|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 [[Oolite Market Scripts|market script]] for this trade good when calculating main station quantities and prices.

'''Note:''' [https://bb.oolite.space/viewtopic.php?p=235837#p235837 What's the difference between the market script specified in planetinfo.plist and the one called for by trade-goods.plist?] (2015)

=== name ===
A string containing the name of the trade good. This may contain [keys]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 [[Oolite_JavaScript_Reference:_Manifest#setShortComment|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.

=== Discussion of classes ===

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)

== Secondary Market Definitions ==

The primary market is that of the system's main station (''i.e.'' the javascript object system.mainStation.market ) Secondary markets are other markets, which are influenced by the primary market, ''e.g.'' that of a local Rock Hermit, or a visiting liner or another orbital station. Both quantities and prices will be influenced by those of the primary market. Needless to say, the primary market is randomly recalculated each time the system is visited.

Secondary market definitions are entered in the [[shipdata.plist#market_definition|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''':

# The market definition array is searched from top to bottom for the first element matching the trade good
# The market quantity is scaled in proportion to the relative capacities for that good in the two markets.
# 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|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 [[shipdata.plist#market_capacity|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 [[shipdata.plist#market_monitored|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.

=== Links ===
*[https://bb.oolite.space/viewtopic.php?f=2&t=21512 Secondary Market Definitions Defined] (2023)

== 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 for determining markets for new stations.

=== From the vanilla game: Rock Hermits ===
The "market_definition" 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: the Trade-goods.plist updated from the original 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;
};

}
=== A new commodity (from the trade-goods.plist inside "SW Economy") ===
"medicine" = {
"name" = "[commodity-name medicine]";
"classes" = ("oolite-consumer","oolite-medical");
"quantity_unit" = 1;
"peak_export" = 7;
"peak_import" = 0;
"price_average" = 640;
"price_economic" = 0.25;
"price_random" = 0.15;
"quantity_average" = 5;
"quantity_economic" = 1.5;
"quantity_random" = 1.0;
"legality_export" = 0;
"legality_import" = 0;
"trumble_opinion" = 0.50;
"sort_order" = 500;
"comment" = "[oolite-commodity-medicine]";
};

=== Setting an orbital main station's slaves on sale to zero ===
[[User:Phkb|Phkb]] provided this example which requires a ''planetinfo.plist'' & a new ''.js file'' - there are other ways to achieve the same result
==== 1) planetinfo.plist (to invoke the market script) ====
(in the "Config" folder)

{
"0 96" = {market_script = "digebiti_noslaves.js";};
}

==== 2) Market script: digebiti_noslaves.js ====
(in the "Scripts" folder) - note the complex name, which prevents confusion with other snippets of script

"use strict";
this.name = "digebiti_noslaves";
this.author = "Phkb";
this.copyright = "(C) 2022 Phkb";
this.licence = "CC-NC-by-SA 4.0";
this.description = "Removes slaves for sale in Digebiti";
this.version = "1.0";

this.updateLocalCommodityDefinition = function(goodDefinition, station, systemID) {
if (goodDefinition.key == "slaves" && station && station.isMainStation) {
goodDefinition.quantity = 0;
}
return goodDefinition;
}

This method will work, so long as no other OXP changes the market_script property of the Digebiti system in the same way.

=== Creating an invariant market independent of the local system economy (agricultural/industrial) ===
If you just use a market_definition in shipdata.plist for the station, then you're merely setting variations on the primary system market.

If you want the station prices to be independent of (or more loosely tied to) the system it's in, then you need to use a [[Oolite_Market_Scripts|market script]].

So what you'd have is something like this - let's say it's a hydroponics station, so it always sells food and nothing else, regardless of whether the general system economy is industrial or agricultural:

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.key == "food") {
// are we calculating the basic Oolite "food" trade good right now? If yes, set our own static prices
goodDefinition.price = 25; // 2.5 credits
goodDefinition.quantity = 80; // lots of food
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

Now ... the reason that market definitions are preferred to be mutators of the system economy is for two reasons.
1) it means you can avoid the situation where you end up with two adjacent stations with wildly different prices ... but you can of course handle that in other ways too, station positioning, restricted access, ''etc''.
2) it makes it easier to handle OXP trade goods:
- other OXPs might have added more "food" type goods, ''e.g.'' "Meat" or "Cheese"
- you can learn about those and handle them specifically

} else if (goodDefinition.key == "bobsfoodoxp_cheese") {
// set price and quantity here

... but that means a lot of keeping up with what everyone else is doing with custom goods.

The idea was that for your hydroponics station what you might do instead is something like this

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So now if another OXP adds Cheese, provided they declare it as "edible", your station will sell it in high quantities at a big discount, but you don't need to know exactly what the baseline price or quantity was set - so if a food-focused OXP was to add "Wine", "Fine Wine" and "Vintage Wine" at a range of prices and quantities, you'd be automatically handling those in reasonable line with a combination of the Wine OXP's basic pricing structure and your station OXP's "food primary source market" style, without necessarily needing to know about every future Wine OXP there might be and explicitly set compatibility.

Note in this example we're still zeroing out all non-food goods - OXP included! - regardless of the local economy. Maybe at this point we'd want to include and document a "hydroponicsoxp-agriculturalequipment" trade good class that other OXPs could use, which this station would buy up at higher demand and prices than normal.

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else if (goodDefinition.classes.indexOf("hydroponicsoxp-agriculturalequipment") >= 0) {
// custom class for other OXPs to add specific agricultural equipment e.g. combine harvesters, compost, fertiliser
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.capacity = 16; // buy a small amount only // TODO: raise capacity if price per tonne is low
goodDefinition.quantity = 0; // not selling this
} else if (goodDefinition.key == "machinery") {
// the basic Oolite Machinery commodity isn't in the custom class but we need to buy something if
// no OXPs adding it are installed
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.quantity = 0; // not selling
goodDefinition.capacity = 16; // small capacity to buy
} else {
// don't buy or sell any other commodity
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So you can see this one has a mix of using, mutating and overruling the definitions set by the system market and OXP commodity definitions ... with this method you could have a whole bunch of OXPs setting up themed stations, and a whole different bunch adding their own custom commodities, and they'd barely have to know about each other to ensure reasonable consistency and compatibility from someone installing any combination of them. (- by [[User:Cim|Cim]], 2023)

Note: this gives examples for 1 commodity at a time, but not how to easily do that for ALL the commodities on ALL the extra stations in a system.

== Using the trade-goods.plist ==
The trade-goods.plist was designed to make commodities simpler, by:
:1) Making it a dictionary rather than an unlabelled array so one could tell which parameter was which
:2) Making the price range for a trade good dependent on more sensible variables, so rather than setting the price range with a bitmask, one set the price and quantity variations dependent on the economy and on random chance.

Compare the v.1.81 trade-goods.plist with a v.1.80 commodities.plist - they were designed to give near-identical market behaviour for the built-in trade goods.

But - that only made it more comprehensible. It didn't really let one do anything particularly different to Elite 84 markets - mostly including the "Rich Industrial -> Poor Agricultural" single spectrum. One can tweak that a bit with peak_export and peak_import to get slightly different shapes (so a good might peak at Poor Industrial rather than Rich Industrial) but it doesn't really give one the option of a third economy type still.

''So how does one introduce a new economic pole, such as a mining industry?''

For that, one needs the scripting support. [[Oolite JavaScript Reference: Market Scripts]]. 
One can quite literally do whatever one likes with the prices that way. One could have every *system* have its own separate economy, which varied over time according to events, what the player had previously traded, ''etc. etc.'' to produce something comparable to Elite Dangerous' economic sim, if that's the route one wanted to go down. Obviously the more complexity one adds the harder it gets to script up, but it's now all possible.

[[File:SOTL Altmap F8.png|thumb|right|200px|SOTL Altmap F8 commodities market]]
[[SOTL Altmap]] does have an example of it, which basically throws out the original Elite-like algorithm of trade-goods.plist and starts over. It goes *way* beyond just adding a third economy, too.

Basically in SOTL every trade good is tagged in the trade-goods.plist with a bunch of classes
''e.g.''
classes = ("sotl-ex-salvage","sotl-im-refining","sotl-quantity-high","sotl-priceband-3","sotl-demand-medium","sotl-supply-medium","sotl-volatility-low");
So that means:
- exported by salvage economies
- imported by refining economies
- high quantity, moderate price, low price volatility

Then the market script uses those classes, rather than the standard pricing variables, to define the economic behaviour.
:So line 69-74ish: get the current economy description, convert that to the format used in the class name
:...line 85-90: check for the import and export classes for that economy and see if it's imported or exported
:...lines 100-120: apply various special conditions, so e.g. the sotl-ims-radiation class checks the planet surface radiation levels (custom property in sysinfo) and if the radiation level is high, imports these goods even if the basic economy isn't interested (e.g. "sotl-ceramics-ind" in the plist)
:...and then it uses those calculations (and a bunch more of the classes) in the rest of the script to set the price and quantity depending on whether it's an import, an export, or neither

That's massive overkill for just adding a third mining economy, but one would need to work on a similar principle.

:1) Tag every commodity with classes for (import|export|none)-(agricultural|industrial|mining) as appropriate
:2) Adjust the economy names (there are a few different ways one could do that) so that the 8 economy IDs were allocated to agricultural, industrial and mining economies
:3) Have a price script which like the SOTL one gets the current economy, looks at the classes list to find out if the commodity is imported or exported or neither, and sets the price and quantity accordingly. One could use the standard price_economic, price_average, price_random properties in the plist to give baseline data to the script if one was not planning to do anything too weird.

{Technically one doesn't need the classes - just have the price script contain a list of goods internally for each economy - but this way if other people add extra trade goods in their own OXPs, they can tag them up for mining economy support too}

All fairly straightforward theoretically.

''The biggest impediment to doing a wholesale reworking of the economic system, is just how incompatible it makes lots and lots of OXP's. In order to override the vanilla commodities as in SOTL, requires setting a script for each in trade-goods.plist. Which is fine if it's the only OXP that wants to play around with commodity prices. As soon as two OXP's try to do the same thing, one gets a conflict and no longer knows which OXP pricing model is in play.''

''For SOTL it's fine, because it uses the scenario system to forcibly eject all other OXP's from use while it's running. But if one wants the OXP to go in the general playing pool set of OXP's, it becomes much more complicated. [[User:Phkb|Phkb]] spent a long time trying to work out why his market script wasn't running, only to find that [[UPS Courier]] was quietly adjusting the markets in certain systems via the planetinfo.plist file. And there are a lot of OXP's that want to play in this space, tweaking prices up or down.''

''Hence one usually abandons using any of the script options, and just tweaks the price after all the scripts have finished playing, ''eg'' in [[Smugglers]]. It was the only way to guarantee getting some sort of bump in a price when wanted.''

== Links ==
*[[Oolite JavaScript Reference: Market Scripts]]
*[[Commodities.plist]] - the precursor (which still mostly works!). If it doesn't see [https://bb.oolite.space/viewtopic.php?p=246145#p246145 here] (2015)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16828 Proposal for 1.82: support for economic changes] ([[User:Cim|Cim]], 2014)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16735 Cim on introducing the Trade-goods.plist and deprecating the commodities.plist] (2014)
{{QuoteText|Text=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.|Source=([https://bb.oolite.space/viewtopic.php?p=226722#p226722 Cim in Progress Thread (2014)])}}
=== Using the Trade-goods.plist ===
*[https://bb.oolite.space/viewtopic.php?f=4&t=20576 How to get the displayName for a commodity in the Main Station Market?] (2020)
*[https://bb.oolite.space/viewtopic.php?f=6&t=17269 Thinking about Planet Income classification] (2015)

{{QuoteText|Text=
In 1.81 this is a lot easier to OXP - you can introduce as many economies as you like, though you are limited to eight economy symbols (so if you wanted lots of economy types, you might end up with Poor Industrial, Avg Industrial and Rich Industrial sharing a symbol on the map). The trade good pricing scripts can then be used to set up different price categories in different economies (and introduce additional trade goods, or split an existing good into multiple categories, which may be necessary if you're adding more economies).

Resetting economies across the planets is a big change in terms of lines of code, but is also very easy to automate. If OXPers are looking for a scripting tool to use for this sort of automation, then NodeJS or io.js is free and also uses Javascript as its language, so you don't need to learn a new one - and may even be able to share code between your build scripts and your OXP, though I haven't tried that yet.|Source=([https://bb.oolite.space/viewtopic.php?f=6&t=17269 Cim in Planet Income thread (2015)])}}

== Preamble ==
To tweak the pricing/availability of commodities in (''eg''.) a station, you need to define the market inside the station's Shipdata.plist - or include a "hook" inside that shipdata.plist to a javascript Oolite Market Script (which allows more complex definitions).

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:

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

== Handlers ==

=== updateGeneralCommodityDefinition ===
{{oolite-method-added|1.81}}
function updateGeneralCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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 = <code>false</code> 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 ===
{{oolite-method-added|1.81}}
function updateLocalCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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.

[https://bb.oolite.space/viewtopic.php?f=4&t=17621#p239979 Here is an example] of how to use this method.

== Links ==

=== Examples ===
*Phkb's update of [[SW_Economy]] (v.3.10) creates new economies for "mining worlds" (hewn out from some low tech poor agricultural worlds) with utterly different price scales for mineral, agricultural & industrial goods, as well as medicine.

''These others will be found at the bottom of the wiki page on the'' [[Trade-goods.plist]].
*Setting an orbital main station's slaves on sale to zero
*Creating an invariant market independent of the local system economy (agricultural/industrial)

Trade-goods (abridged)

2026-06-19T08:45:39Z

Wildeblood: /* Discussion of classes */

'''You are probably looking for [[Trade-goods.plist]]''', rather than this page.

== F.A.Q. ==

The goal of this page is to answer the following questions.

=== How many different places can market influences be hiding? ===

In plists, in market scripts, and in station methods in ''any damned script''.

2. Which plists exactly?

At least trade-goods.plist , shipdata.plist , shipdata-overides.plist (sp?), planetinfo.plist

3. Which market scripts exactly?

4. What methods?

== Preamble ==

The trade-goods.plist file defines "trade goods" (commodities/cargo). But, it does not ''e.g.'' remove slaves from a particular station or make them cost twice as much as they do at the main orbital station. To do such things, ''i.e.'' to tweak the pricing/availability of commodities in a particular station, you need to define the market inside that station, either within its [[Shipdata.plist]] or within a [[Oolite_Market_Scripts|market script]] linked from its shipdata.plist.

== Overview ==

The '''trade-goods.plist''' file is a dictionary of dictionaries, with (canonical) commodity names as keys to dictionaries of key-value pairs 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 [[Oolite_JavaScript_Reference:_Manifest#setComment|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 [[Oolite Market Scripts|market script]] for this trade good when calculating main station quantities and prices.

'''Note:''' [https://bb.oolite.space/viewtopic.php?p=235837#p235837 What's the difference between the market script specified in planetinfo.plist and the one called for by trade-goods.plist?] (2015)

=== name ===
A string containing the name of the trade good. This may contain [keys]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 [[Oolite_JavaScript_Reference:_Manifest#setShortComment|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.

=== Discussion of classes ===

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)

== Secondary Market Definitions ==

The primary market is that of the system's main station (''i.e.'' the javascript object system.mainStation.market ) Secondary markets are other markets, which are influenced by the primary market, ''e.g.'' that of a local Rock Hermit, or a visiting liner or another orbital station. Both quantities and prices will be influenced by those of the primary market. Needless to say, the primary market is randomly recalculated each time the system is visited.

Secondary market definitions are entered in the [[shipdata.plist#market_definition|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''':

# The market definition array is searched from top to bottom for the first element matching the trade good
# The market quantity is scaled in proportion to the relative capacities for that good in the two markets.
# 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|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 [[shipdata.plist#market_capacity|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 [[shipdata.plist#market_monitored|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.

=== Links ===
*[https://bb.oolite.space/viewtopic.php?f=2&t=21512 Secondary Market Definitions Defined] (2023)

== 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 for determining markets for new stations.

=== From the vanilla game: Rock Hermits ===
The "market_definition" 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: the Trade-goods.plist updated from the original 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;
};

}
=== A new commodity (from the trade-goods.plist inside "SW Economy") ===
"medicine" = {
"name" = "[commodity-name medicine]";
"classes" = ("oolite-consumer","oolite-medical");
"quantity_unit" = 1;
"peak_export" = 7;
"peak_import" = 0;
"price_average" = 640;
"price_economic" = 0.25;
"price_random" = 0.15;
"quantity_average" = 5;
"quantity_economic" = 1.5;
"quantity_random" = 1.0;
"legality_export" = 0;
"legality_import" = 0;
"trumble_opinion" = 0.50;
"sort_order" = 500;
"comment" = "[oolite-commodity-medicine]";
};

=== Setting an orbital main station's slaves on sale to zero ===
[[User:Phkb|Phkb]] provided this example which requires a ''planetinfo.plist'' & a new ''.js file'' - there are other ways to achieve the same result
==== 1) planetinfo.plist (to invoke the market script) ====
(in the "Config" folder)

{
"0 96" = {market_script = "digebiti_noslaves.js";};
}

==== 2) Market script: digebiti_noslaves.js ====
(in the "Scripts" folder) - note the complex name, which prevents confusion with other snippets of script

"use strict";
this.name = "digebiti_noslaves";
this.author = "Phkb";
this.copyright = "(C) 2022 Phkb";
this.licence = "CC-NC-by-SA 4.0";
this.description = "Removes slaves for sale in Digebiti";
this.version = "1.0";

this.updateLocalCommodityDefinition = function(goodDefinition, station, systemID) {
if (goodDefinition.key == "slaves" && station && station.isMainStation) {
goodDefinition.quantity = 0;
}
return goodDefinition;
}

This method will work, so long as no other OXP changes the market_script property of the Digebiti system in the same way.

=== Creating an invariant market independent of the local system economy (agricultural/industrial) ===
If you just use a market_definition in shipdata.plist for the station, then you're merely setting variations on the primary system market.

If you want the station prices to be independent of (or more loosely tied to) the system it's in, then you need to use a [[Oolite_Market_Scripts|market script]].

So what you'd have is something like this - let's say it's a hydroponics station, so it always sells food and nothing else, regardless of whether the general system economy is industrial or agricultural:

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.key == "food") {
// are we calculating the basic Oolite "food" trade good right now? If yes, set our own static prices
goodDefinition.price = 25; // 2.5 credits
goodDefinition.quantity = 80; // lots of food
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

Now ... the reason that market definitions are preferred to be mutators of the system economy is for two reasons.
1) it means you can avoid the situation where you end up with two adjacent stations with wildly different prices ... but you can of course handle that in other ways too, station positioning, restricted access, ''etc''.
2) it makes it easier to handle OXP trade goods:
- other OXPs might have added more "food" type goods, ''e.g.'' "Meat" or "Cheese"
- you can learn about those and handle them specifically

} else if (goodDefinition.key == "bobsfoodoxp_cheese") {
// set price and quantity here

... but that means a lot of keeping up with what everyone else is doing with custom goods.

The idea was that for your hydroponics station what you might do instead is something like this

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So now if another OXP adds Cheese, provided they declare it as "edible", your station will sell it in high quantities at a big discount, but you don't need to know exactly what the baseline price or quantity was set - so if a food-focused OXP was to add "Wine", "Fine Wine" and "Vintage Wine" at a range of prices and quantities, you'd be automatically handling those in reasonable line with a combination of the Wine OXP's basic pricing structure and your station OXP's "food primary source market" style, without necessarily needing to know about every future Wine OXP there might be and explicitly set compatibility.

Note in this example we're still zeroing out all non-food goods - OXP included! - regardless of the local economy. Maybe at this point we'd want to include and document a "hydroponicsoxp-agriculturalequipment" trade good class that other OXPs could use, which this station would buy up at higher demand and prices than normal.

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else if (goodDefinition.classes.indexOf("hydroponicsoxp-agriculturalequipment") >= 0) {
// custom class for other OXPs to add specific agricultural equipment e.g. combine harvesters, compost, fertiliser
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.capacity = 16; // buy a small amount only // TODO: raise capacity if price per tonne is low
goodDefinition.quantity = 0; // not selling this
} else if (goodDefinition.key == "machinery") {
// the basic Oolite Machinery commodity isn't in the custom class but we need to buy something if
// no OXPs adding it are installed
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.quantity = 0; // not selling
goodDefinition.capacity = 16; // small capacity to buy
} else {
// don't buy or sell any other commodity
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So you can see this one has a mix of using, mutating and overruling the definitions set by the system market and OXP commodity definitions ... with this method you could have a whole bunch of OXPs setting up themed stations, and a whole different bunch adding their own custom commodities, and they'd barely have to know about each other to ensure reasonable consistency and compatibility from someone installing any combination of them. (- by [[User:Cim|Cim]], 2023)

Note: this gives examples for 1 commodity at a time, but not how to easily do that for ALL the commodities on ALL the extra stations in a system.

== Using the trade-goods.plist ==
The trade-goods.plist was designed to make commodities simpler, by:
:1) Making it a dictionary rather than an unlabelled array so one could tell which parameter was which
:2) Making the price range for a trade good dependent on more sensible variables, so rather than setting the price range with a bitmask, one set the price and quantity variations dependent on the economy and on random chance.

Compare the v.1.81 trade-goods.plist with a v.1.80 commodities.plist - they were designed to give near-identical market behaviour for the built-in trade goods.

But - that only made it more comprehensible. It didn't really let one do anything particularly different to Elite 84 markets - mostly including the "Rich Industrial -> Poor Agricultural" single spectrum. One can tweak that a bit with peak_export and peak_import to get slightly different shapes (so a good might peak at Poor Industrial rather than Rich Industrial) but it doesn't really give one the option of a third economy type still.

''So how does one introduce a new economic pole, such as a mining industry?''

For that, one needs the scripting support. [[Oolite JavaScript Reference: Market Scripts]]. 
One can quite literally do whatever one likes with the prices that way. One could have every *system* have its own separate economy, which varied over time according to events, what the player had previously traded, ''etc. etc.'' to produce something comparable to Elite Dangerous' economic sim, if that's the route one wanted to go down. Obviously the more complexity one adds the harder it gets to script up, but it's now all possible.

[[File:SOTL Altmap F8.png|thumb|right|200px|SOTL Altmap F8 commodities market]]
[[SOTL Altmap]] does have an example of it, which basically throws out the original Elite-like algorithm of trade-goods.plist and starts over. It goes *way* beyond just adding a third economy, too.

Basically in SOTL every trade good is tagged in the trade-goods.plist with a bunch of classes
''e.g.''
classes = ("sotl-ex-salvage","sotl-im-refining","sotl-quantity-high","sotl-priceband-3","sotl-demand-medium","sotl-supply-medium","sotl-volatility-low");
So that means:
- exported by salvage economies
- imported by refining economies
- high quantity, moderate price, low price volatility

Then the market script uses those classes, rather than the standard pricing variables, to define the economic behaviour.
:So line 69-74ish: get the current economy description, convert that to the format used in the class name
:...line 85-90: check for the import and export classes for that economy and see if it's imported or exported
:...lines 100-120: apply various special conditions, so e.g. the sotl-ims-radiation class checks the planet surface radiation levels (custom property in sysinfo) and if the radiation level is high, imports these goods even if the basic economy isn't interested (e.g. "sotl-ceramics-ind" in the plist)
:...and then it uses those calculations (and a bunch more of the classes) in the rest of the script to set the price and quantity depending on whether it's an import, an export, or neither

That's massive overkill for just adding a third mining economy, but one would need to work on a similar principle.

:1) Tag every commodity with classes for (import|export|none)-(agricultural|industrial|mining) as appropriate
:2) Adjust the economy names (there are a few different ways one could do that) so that the 8 economy IDs were allocated to agricultural, industrial and mining economies
:3) Have a price script which like the SOTL one gets the current economy, looks at the classes list to find out if the commodity is imported or exported or neither, and sets the price and quantity accordingly. One could use the standard price_economic, price_average, price_random properties in the plist to give baseline data to the script if one was not planning to do anything too weird.

{Technically one doesn't need the classes - just have the price script contain a list of goods internally for each economy - but this way if other people add extra trade goods in their own OXPs, they can tag them up for mining economy support too}

All fairly straightforward theoretically.

''The biggest impediment to doing a wholesale reworking of the economic system, is just how incompatible it makes lots and lots of OXP's. In order to override the vanilla commodities as in SOTL, requires setting a script for each in trade-goods.plist. Which is fine if it's the only OXP that wants to play around with commodity prices. As soon as two OXP's try to do the same thing, one gets a conflict and no longer knows which OXP pricing model is in play.''

''For SOTL it's fine, because it uses the scenario system to forcibly eject all other OXP's from use while it's running. But if one wants the OXP to go in the general playing pool set of OXP's, it becomes much more complicated. [[User:Phkb|Phkb]] spent a long time trying to work out why his market script wasn't running, only to find that [[UPS Courier]] was quietly adjusting the markets in certain systems via the planetinfo.plist file. And there are a lot of OXP's that want to play in this space, tweaking prices up or down.''

''Hence one usually abandons using any of the script options, and just tweaks the price after all the scripts have finished playing, ''eg'' in [[Smugglers]]. It was the only way to guarantee getting some sort of bump in a price when wanted.''

== Links ==
*[[Oolite JavaScript Reference: Market Scripts]]
*[[Commodities.plist]] - the precursor (which still mostly works!). If it doesn't see [https://bb.oolite.space/viewtopic.php?p=246145#p246145 here] (2015)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16828 Proposal for 1.82: support for economic changes] ([[User:Cim|Cim]], 2014)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16735 Cim on introducing the Trade-goods.plist and deprecating the commodities.plist] (2014)
{{QuoteText|Text=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.|Source=([https://bb.oolite.space/viewtopic.php?p=226722#p226722 Cim in Progress Thread (2014)])}}
=== Using the Trade-goods.plist ===
*[https://bb.oolite.space/viewtopic.php?f=4&t=20576 How to get the displayName for a commodity in the Main Station Market?] (2020)
*[https://bb.oolite.space/viewtopic.php?f=6&t=17269 Thinking about Planet Income classification] (2015)

{{QuoteText|Text=
In 1.81 this is a lot easier to OXP - you can introduce as many economies as you like, though you are limited to eight economy symbols (so if you wanted lots of economy types, you might end up with Poor Industrial, Avg Industrial and Rich Industrial sharing a symbol on the map). The trade good pricing scripts can then be used to set up different price categories in different economies (and introduce additional trade goods, or split an existing good into multiple categories, which may be necessary if you're adding more economies).

Resetting economies across the planets is a big change in terms of lines of code, but is also very easy to automate. If OXPers are looking for a scripting tool to use for this sort of automation, then NodeJS or io.js is free and also uses Javascript as its language, so you don't need to learn a new one - and may even be able to share code between your build scripts and your OXP, though I haven't tried that yet.|Source=([https://bb.oolite.space/viewtopic.php?f=6&t=17269 Cim in Planet Income thread (2015)])}}

== Preamble ==
To tweak the pricing/availability of commodities in (''eg''.) a station, you need to define the market inside the station's Shipdata.plist - or include a "hook" inside that shipdata.plist to a javascript Oolite Market Script (which allows more complex definitions).

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:

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

== Handlers ==

=== updateGeneralCommodityDefinition ===
{{oolite-method-added|1.81}}
function updateGeneralCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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 = <code>false</code> 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 ===
{{oolite-method-added|1.81}}
function updateLocalCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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.

[https://bb.oolite.space/viewtopic.php?f=4&t=17621#p239979 Here is an example] of how to use this method.

== Links ==

=== Examples ===
*Phkb's update of [[SW_Economy]] (v.3.10) creates new economies for "mining worlds" (hewn out from some low tech poor agricultural worlds) with utterly different price scales for mineral, agricultural & industrial goods, as well as medicine.

''These others will be found at the bottom of the wiki page on the'' [[Trade-goods.plist]].
*Setting an orbital main station's slaves on sale to zero
*Creating an invariant market independent of the local system economy (agricultural/industrial)

Trade-goods (abridged)

2026-06-19T08:41:07Z

Wildeblood: /* trumble_opinion */

'''You are probably looking for [[Trade-goods.plist]]''', rather than this page.

== F.A.Q. ==

The goal of this page is to answer the following questions.

=== How many different places can market influences be hiding? ===

In plists, in market scripts, and in station methods in ''any damned script''.

2. Which plists exactly?

At least trade-goods.plist , shipdata.plist , shipdata-overides.plist (sp?), planetinfo.plist

3. Which market scripts exactly?

4. What methods?

== Preamble ==

The trade-goods.plist file defines "trade goods" (commodities/cargo). But, it does not ''e.g.'' remove slaves from a particular station or make them cost twice as much as they do at the main orbital station. To do such things, ''i.e.'' to tweak the pricing/availability of commodities in a particular station, you need to define the market inside that station, either within its [[Shipdata.plist]] or within a [[Oolite_Market_Scripts|market script]] linked from its shipdata.plist.

== Overview ==

The '''trade-goods.plist''' file is a dictionary of dictionaries, with (canonical) commodity names as keys to dictionaries of key-value pairs 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 [[Oolite_JavaScript_Reference:_Manifest#setComment|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 [[Oolite Market Scripts|market script]] for this trade good when calculating main station quantities and prices.

'''Note:''' [https://bb.oolite.space/viewtopic.php?p=235837#p235837 What's the difference between the market script specified in planetinfo.plist and the one called for by trade-goods.plist?] (2015)

=== name ===
A string containing the name of the trade good. This may contain [keys]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 [[Oolite_JavaScript_Reference:_Manifest#setShortComment|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.

=== Discussion of classes ===

HERE

== Secondary Market Definitions ==

The primary market is that of the system's main station (''i.e.'' the javascript object system.mainStation.market ) Secondary markets are other markets, which are influenced by the primary market, ''e.g.'' that of a local Rock Hermit, or a visiting liner or another orbital station. Both quantities and prices will be influenced by those of the primary market. Needless to say, the primary market is randomly recalculated each time the system is visited.

Secondary market definitions are entered in the [[shipdata.plist#market_definition|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''':

# The market definition array is searched from top to bottom for the first element matching the trade good
# The market quantity is scaled in proportion to the relative capacities for that good in the two markets.
# 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|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 [[shipdata.plist#market_capacity|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 [[shipdata.plist#market_monitored|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.

=== Links ===
*[https://bb.oolite.space/viewtopic.php?f=2&t=21512 Secondary Market Definitions Defined] (2023)

== 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 for determining markets for new stations.

=== From the vanilla game: Rock Hermits ===
The "market_definition" 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: the Trade-goods.plist updated from the original 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;
};

}
=== A new commodity (from the trade-goods.plist inside "SW Economy") ===
"medicine" = {
"name" = "[commodity-name medicine]";
"classes" = ("oolite-consumer","oolite-medical");
"quantity_unit" = 1;
"peak_export" = 7;
"peak_import" = 0;
"price_average" = 640;
"price_economic" = 0.25;
"price_random" = 0.15;
"quantity_average" = 5;
"quantity_economic" = 1.5;
"quantity_random" = 1.0;
"legality_export" = 0;
"legality_import" = 0;
"trumble_opinion" = 0.50;
"sort_order" = 500;
"comment" = "[oolite-commodity-medicine]";
};

=== Setting an orbital main station's slaves on sale to zero ===
[[User:Phkb|Phkb]] provided this example which requires a ''planetinfo.plist'' & a new ''.js file'' - there are other ways to achieve the same result
==== 1) planetinfo.plist (to invoke the market script) ====
(in the "Config" folder)

{
"0 96" = {market_script = "digebiti_noslaves.js";};
}

==== 2) Market script: digebiti_noslaves.js ====
(in the "Scripts" folder) - note the complex name, which prevents confusion with other snippets of script

"use strict";
this.name = "digebiti_noslaves";
this.author = "Phkb";
this.copyright = "(C) 2022 Phkb";
this.licence = "CC-NC-by-SA 4.0";
this.description = "Removes slaves for sale in Digebiti";
this.version = "1.0";

this.updateLocalCommodityDefinition = function(goodDefinition, station, systemID) {
if (goodDefinition.key == "slaves" && station && station.isMainStation) {
goodDefinition.quantity = 0;
}
return goodDefinition;
}

This method will work, so long as no other OXP changes the market_script property of the Digebiti system in the same way.

=== Creating an invariant market independent of the local system economy (agricultural/industrial) ===
If you just use a market_definition in shipdata.plist for the station, then you're merely setting variations on the primary system market.

If you want the station prices to be independent of (or more loosely tied to) the system it's in, then you need to use a [[Oolite_Market_Scripts|market script]].

So what you'd have is something like this - let's say it's a hydroponics station, so it always sells food and nothing else, regardless of whether the general system economy is industrial or agricultural:

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.key == "food") {
// are we calculating the basic Oolite "food" trade good right now? If yes, set our own static prices
goodDefinition.price = 25; // 2.5 credits
goodDefinition.quantity = 80; // lots of food
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

Now ... the reason that market definitions are preferred to be mutators of the system economy is for two reasons.
1) it means you can avoid the situation where you end up with two adjacent stations with wildly different prices ... but you can of course handle that in other ways too, station positioning, restricted access, ''etc''.
2) it makes it easier to handle OXP trade goods:
- other OXPs might have added more "food" type goods, ''e.g.'' "Meat" or "Cheese"
- you can learn about those and handle them specifically

} else if (goodDefinition.key == "bobsfoodoxp_cheese") {
// set price and quantity here

... but that means a lot of keeping up with what everyone else is doing with custom goods.

The idea was that for your hydroponics station what you might do instead is something like this

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So now if another OXP adds Cheese, provided they declare it as "edible", your station will sell it in high quantities at a big discount, but you don't need to know exactly what the baseline price or quantity was set - so if a food-focused OXP was to add "Wine", "Fine Wine" and "Vintage Wine" at a range of prices and quantities, you'd be automatically handling those in reasonable line with a combination of the Wine OXP's basic pricing structure and your station OXP's "food primary source market" style, without necessarily needing to know about every future Wine OXP there might be and explicitly set compatibility.

Note in this example we're still zeroing out all non-food goods - OXP included! - regardless of the local economy. Maybe at this point we'd want to include and document a "hydroponicsoxp-agriculturalequipment" trade good class that other OXPs could use, which this station would buy up at higher demand and prices than normal.

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else if (goodDefinition.classes.indexOf("hydroponicsoxp-agriculturalequipment") >= 0) {
// custom class for other OXPs to add specific agricultural equipment e.g. combine harvesters, compost, fertiliser
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.capacity = 16; // buy a small amount only // TODO: raise capacity if price per tonne is low
goodDefinition.quantity = 0; // not selling this
} else if (goodDefinition.key == "machinery") {
// the basic Oolite Machinery commodity isn't in the custom class but we need to buy something if
// no OXPs adding it are installed
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.quantity = 0; // not selling
goodDefinition.capacity = 16; // small capacity to buy
} else {
// don't buy or sell any other commodity
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So you can see this one has a mix of using, mutating and overruling the definitions set by the system market and OXP commodity definitions ... with this method you could have a whole bunch of OXPs setting up themed stations, and a whole different bunch adding their own custom commodities, and they'd barely have to know about each other to ensure reasonable consistency and compatibility from someone installing any combination of them. (- by [[User:Cim|Cim]], 2023)

Note: this gives examples for 1 commodity at a time, but not how to easily do that for ALL the commodities on ALL the extra stations in a system.

== Using the trade-goods.plist ==
The trade-goods.plist was designed to make commodities simpler, by:
:1) Making it a dictionary rather than an unlabelled array so one could tell which parameter was which
:2) Making the price range for a trade good dependent on more sensible variables, so rather than setting the price range with a bitmask, one set the price and quantity variations dependent on the economy and on random chance.

Compare the v.1.81 trade-goods.plist with a v.1.80 commodities.plist - they were designed to give near-identical market behaviour for the built-in trade goods.

But - that only made it more comprehensible. It didn't really let one do anything particularly different to Elite 84 markets - mostly including the "Rich Industrial -> Poor Agricultural" single spectrum. One can tweak that a bit with peak_export and peak_import to get slightly different shapes (so a good might peak at Poor Industrial rather than Rich Industrial) but it doesn't really give one the option of a third economy type still.

''So how does one introduce a new economic pole, such as a mining industry?''

For that, one needs the scripting support. [[Oolite JavaScript Reference: Market Scripts]]. 
One can quite literally do whatever one likes with the prices that way. One could have every *system* have its own separate economy, which varied over time according to events, what the player had previously traded, ''etc. etc.'' to produce something comparable to Elite Dangerous' economic sim, if that's the route one wanted to go down. Obviously the more complexity one adds the harder it gets to script up, but it's now all possible.

[[File:SOTL Altmap F8.png|thumb|right|200px|SOTL Altmap F8 commodities market]]
[[SOTL Altmap]] does have an example of it, which basically throws out the original Elite-like algorithm of trade-goods.plist and starts over. It goes *way* beyond just adding a third economy, too.

Basically in SOTL every trade good is tagged in the trade-goods.plist with a bunch of classes
''e.g.''
classes = ("sotl-ex-salvage","sotl-im-refining","sotl-quantity-high","sotl-priceband-3","sotl-demand-medium","sotl-supply-medium","sotl-volatility-low");
So that means:
- exported by salvage economies
- imported by refining economies
- high quantity, moderate price, low price volatility

Then the market script uses those classes, rather than the standard pricing variables, to define the economic behaviour.
:So line 69-74ish: get the current economy description, convert that to the format used in the class name
:...line 85-90: check for the import and export classes for that economy and see if it's imported or exported
:...lines 100-120: apply various special conditions, so e.g. the sotl-ims-radiation class checks the planet surface radiation levels (custom property in sysinfo) and if the radiation level is high, imports these goods even if the basic economy isn't interested (e.g. "sotl-ceramics-ind" in the plist)
:...and then it uses those calculations (and a bunch more of the classes) in the rest of the script to set the price and quantity depending on whether it's an import, an export, or neither

That's massive overkill for just adding a third mining economy, but one would need to work on a similar principle.

:1) Tag every commodity with classes for (import|export|none)-(agricultural|industrial|mining) as appropriate
:2) Adjust the economy names (there are a few different ways one could do that) so that the 8 economy IDs were allocated to agricultural, industrial and mining economies
:3) Have a price script which like the SOTL one gets the current economy, looks at the classes list to find out if the commodity is imported or exported or neither, and sets the price and quantity accordingly. One could use the standard price_economic, price_average, price_random properties in the plist to give baseline data to the script if one was not planning to do anything too weird.

{Technically one doesn't need the classes - just have the price script contain a list of goods internally for each economy - but this way if other people add extra trade goods in their own OXPs, they can tag them up for mining economy support too}

All fairly straightforward theoretically.

''The biggest impediment to doing a wholesale reworking of the economic system, is just how incompatible it makes lots and lots of OXP's. In order to override the vanilla commodities as in SOTL, requires setting a script for each in trade-goods.plist. Which is fine if it's the only OXP that wants to play around with commodity prices. As soon as two OXP's try to do the same thing, one gets a conflict and no longer knows which OXP pricing model is in play.''

''For SOTL it's fine, because it uses the scenario system to forcibly eject all other OXP's from use while it's running. But if one wants the OXP to go in the general playing pool set of OXP's, it becomes much more complicated. [[User:Phkb|Phkb]] spent a long time trying to work out why his market script wasn't running, only to find that [[UPS Courier]] was quietly adjusting the markets in certain systems via the planetinfo.plist file. And there are a lot of OXP's that want to play in this space, tweaking prices up or down.''

''Hence one usually abandons using any of the script options, and just tweaks the price after all the scripts have finished playing, ''eg'' in [[Smugglers]]. It was the only way to guarantee getting some sort of bump in a price when wanted.''

== Links ==
*[[Oolite JavaScript Reference: Market Scripts]]
*[[Commodities.plist]] - the precursor (which still mostly works!). If it doesn't see [https://bb.oolite.space/viewtopic.php?p=246145#p246145 here] (2015)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16828 Proposal for 1.82: support for economic changes] ([[User:Cim|Cim]], 2014)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16735 Cim on introducing the Trade-goods.plist and deprecating the commodities.plist] (2014)
{{QuoteText|Text=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.|Source=([https://bb.oolite.space/viewtopic.php?p=226722#p226722 Cim in Progress Thread (2014)])}}
=== Using the Trade-goods.plist ===
*[https://bb.oolite.space/viewtopic.php?f=4&t=20576 How to get the displayName for a commodity in the Main Station Market?] (2020)
*[https://bb.oolite.space/viewtopic.php?f=6&t=17269 Thinking about Planet Income classification] (2015)

{{QuoteText|Text=
In 1.81 this is a lot easier to OXP - you can introduce as many economies as you like, though you are limited to eight economy symbols (so if you wanted lots of economy types, you might end up with Poor Industrial, Avg Industrial and Rich Industrial sharing a symbol on the map). The trade good pricing scripts can then be used to set up different price categories in different economies (and introduce additional trade goods, or split an existing good into multiple categories, which may be necessary if you're adding more economies).

Resetting economies across the planets is a big change in terms of lines of code, but is also very easy to automate. If OXPers are looking for a scripting tool to use for this sort of automation, then NodeJS or io.js is free and also uses Javascript as its language, so you don't need to learn a new one - and may even be able to share code between your build scripts and your OXP, though I haven't tried that yet.|Source=([https://bb.oolite.space/viewtopic.php?f=6&t=17269 Cim in Planet Income thread (2015)])}}

== Preamble ==
To tweak the pricing/availability of commodities in (''eg''.) a station, you need to define the market inside the station's Shipdata.plist - or include a "hook" inside that shipdata.plist to a javascript Oolite Market Script (which allows more complex definitions).

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:

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

== Handlers ==

=== updateGeneralCommodityDefinition ===
{{oolite-method-added|1.81}}
function updateGeneralCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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 = <code>false</code> 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 ===
{{oolite-method-added|1.81}}
function updateLocalCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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.

[https://bb.oolite.space/viewtopic.php?f=4&t=17621#p239979 Here is an example] of how to use this method.

== Links ==

=== Examples ===
*Phkb's update of [[SW_Economy]] (v.3.10) creates new economies for "mining worlds" (hewn out from some low tech poor agricultural worlds) with utterly different price scales for mineral, agricultural & industrial goods, as well as medicine.

''These others will be found at the bottom of the wiki page on the'' [[Trade-goods.plist]].
*Setting an orbital main station's slaves on sale to zero
*Creating an invariant market independent of the local system economy (agricultural/industrial)

Trade-goods (abridged)

2026-06-19T08:31:22Z

Wildeblood: /* F.A.Q. */

'''You are probably looking for [[Trade-goods.plist]]''', rather than this page.

== F.A.Q. ==

The goal of this page is to answer the following questions.

=== How many different places can market influences be hiding? ===

In plists, in market scripts, and in station methods in ''any damned script''.

2. Which plists exactly?

At least trade-goods.plist , shipdata.plist , shipdata-overides.plist (sp?), planetinfo.plist

3. Which market scripts exactly?

4. What methods?

== Preamble ==

The trade-goods.plist file defines "trade goods" (commodities/cargo). But, it does not ''e.g.'' remove slaves from a particular station or make them cost twice as much as they do at the main orbital station. To do such things, ''i.e.'' to tweak the pricing/availability of commodities in a particular station, you need to define the market inside that station, either within its [[Shipdata.plist]] or within a [[Oolite_Market_Scripts|market script]] linked from its shipdata.plist.

== Overview ==

The '''trade-goods.plist''' file is a dictionary of dictionaries, with (canonical) commodity names as keys to dictionaries of key-value pairs 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 [[Oolite_JavaScript_Reference:_Manifest#setComment|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 [[Oolite Market Scripts|market script]] for this trade good when calculating main station quantities and prices.

'''Note:''' [https://bb.oolite.space/viewtopic.php?p=235837#p235837 What's the difference between the market script specified in planetinfo.plist and the one called for by trade-goods.plist?] (2015)

=== name ===
A string containing the name of the trade good. This may contain [keys]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 [[Oolite_JavaScript_Reference:_Manifest#setShortComment|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 ==

The primary market is that of the system's main station (''i.e.'' the javascript object system.mainStation.market ) Secondary markets are other markets, which are influenced by the primary market, ''e.g.'' that of a local Rock Hermit, or a visiting liner or another orbital station. Both quantities and prices will be influenced by those of the primary market. Needless to say, the primary market is randomly recalculated each time the system is visited.

Secondary market definitions are entered in the [[shipdata.plist#market_definition|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''':

# The market definition array is searched from top to bottom for the first element matching the trade good
# The market quantity is scaled in proportion to the relative capacities for that good in the two markets.
# 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|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 [[shipdata.plist#market_capacity|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 [[shipdata.plist#market_monitored|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.

=== Links ===
*[https://bb.oolite.space/viewtopic.php?f=2&t=21512 Secondary Market Definitions Defined] (2023)

== 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 for determining markets for new stations.

=== From the vanilla game: Rock Hermits ===
The "market_definition" 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: the Trade-goods.plist updated from the original 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;
};

}
=== A new commodity (from the trade-goods.plist inside "SW Economy") ===
"medicine" = {
"name" = "[commodity-name medicine]";
"classes" = ("oolite-consumer","oolite-medical");
"quantity_unit" = 1;
"peak_export" = 7;
"peak_import" = 0;
"price_average" = 640;
"price_economic" = 0.25;
"price_random" = 0.15;
"quantity_average" = 5;
"quantity_economic" = 1.5;
"quantity_random" = 1.0;
"legality_export" = 0;
"legality_import" = 0;
"trumble_opinion" = 0.50;
"sort_order" = 500;
"comment" = "[oolite-commodity-medicine]";
};

=== Setting an orbital main station's slaves on sale to zero ===
[[User:Phkb|Phkb]] provided this example which requires a ''planetinfo.plist'' & a new ''.js file'' - there are other ways to achieve the same result
==== 1) planetinfo.plist (to invoke the market script) ====
(in the "Config" folder)

{
"0 96" = {market_script = "digebiti_noslaves.js";};
}

==== 2) Market script: digebiti_noslaves.js ====
(in the "Scripts" folder) - note the complex name, which prevents confusion with other snippets of script

"use strict";
this.name = "digebiti_noslaves";
this.author = "Phkb";
this.copyright = "(C) 2022 Phkb";
this.licence = "CC-NC-by-SA 4.0";
this.description = "Removes slaves for sale in Digebiti";
this.version = "1.0";

this.updateLocalCommodityDefinition = function(goodDefinition, station, systemID) {
if (goodDefinition.key == "slaves" && station && station.isMainStation) {
goodDefinition.quantity = 0;
}
return goodDefinition;
}

This method will work, so long as no other OXP changes the market_script property of the Digebiti system in the same way.

=== Creating an invariant market independent of the local system economy (agricultural/industrial) ===
If you just use a market_definition in shipdata.plist for the station, then you're merely setting variations on the primary system market.

If you want the station prices to be independent of (or more loosely tied to) the system it's in, then you need to use a [[Oolite_Market_Scripts|market script]].

So what you'd have is something like this - let's say it's a hydroponics station, so it always sells food and nothing else, regardless of whether the general system economy is industrial or agricultural:

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.key == "food") {
// are we calculating the basic Oolite "food" trade good right now? If yes, set our own static prices
goodDefinition.price = 25; // 2.5 credits
goodDefinition.quantity = 80; // lots of food
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

Now ... the reason that market definitions are preferred to be mutators of the system economy is for two reasons.
1) it means you can avoid the situation where you end up with two adjacent stations with wildly different prices ... but you can of course handle that in other ways too, station positioning, restricted access, ''etc''.
2) it makes it easier to handle OXP trade goods:
- other OXPs might have added more "food" type goods, ''e.g.'' "Meat" or "Cheese"
- you can learn about those and handle them specifically

} else if (goodDefinition.key == "bobsfoodoxp_cheese") {
// set price and quantity here

... but that means a lot of keeping up with what everyone else is doing with custom goods.

The idea was that for your hydroponics station what you might do instead is something like this

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So now if another OXP adds Cheese, provided they declare it as "edible", your station will sell it in high quantities at a big discount, but you don't need to know exactly what the baseline price or quantity was set - so if a food-focused OXP was to add "Wine", "Fine Wine" and "Vintage Wine" at a range of prices and quantities, you'd be automatically handling those in reasonable line with a combination of the Wine OXP's basic pricing structure and your station OXP's "food primary source market" style, without necessarily needing to know about every future Wine OXP there might be and explicitly set compatibility.

Note in this example we're still zeroing out all non-food goods - OXP included! - regardless of the local economy. Maybe at this point we'd want to include and document a "hydroponicsoxp-agriculturalequipment" trade good class that other OXPs could use, which this station would buy up at higher demand and prices than normal.

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else if (goodDefinition.classes.indexOf("hydroponicsoxp-agriculturalequipment") >= 0) {
// custom class for other OXPs to add specific agricultural equipment e.g. combine harvesters, compost, fertiliser
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.capacity = 16; // buy a small amount only // TODO: raise capacity if price per tonne is low
goodDefinition.quantity = 0; // not selling this
} else if (goodDefinition.key == "machinery") {
// the basic Oolite Machinery commodity isn't in the custom class but we need to buy something if
// no OXPs adding it are installed
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.quantity = 0; // not selling
goodDefinition.capacity = 16; // small capacity to buy
} else {
// don't buy or sell any other commodity
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So you can see this one has a mix of using, mutating and overruling the definitions set by the system market and OXP commodity definitions ... with this method you could have a whole bunch of OXPs setting up themed stations, and a whole different bunch adding their own custom commodities, and they'd barely have to know about each other to ensure reasonable consistency and compatibility from someone installing any combination of them. (- by [[User:Cim|Cim]], 2023)

Note: this gives examples for 1 commodity at a time, but not how to easily do that for ALL the commodities on ALL the extra stations in a system.

== Using the trade-goods.plist ==
The trade-goods.plist was designed to make commodities simpler, by:
:1) Making it a dictionary rather than an unlabelled array so one could tell which parameter was which
:2) Making the price range for a trade good dependent on more sensible variables, so rather than setting the price range with a bitmask, one set the price and quantity variations dependent on the economy and on random chance.

Compare the v.1.81 trade-goods.plist with a v.1.80 commodities.plist - they were designed to give near-identical market behaviour for the built-in trade goods.

But - that only made it more comprehensible. It didn't really let one do anything particularly different to Elite 84 markets - mostly including the "Rich Industrial -> Poor Agricultural" single spectrum. One can tweak that a bit with peak_export and peak_import to get slightly different shapes (so a good might peak at Poor Industrial rather than Rich Industrial) but it doesn't really give one the option of a third economy type still.

''So how does one introduce a new economic pole, such as a mining industry?''

For that, one needs the scripting support. [[Oolite JavaScript Reference: Market Scripts]]. 
One can quite literally do whatever one likes with the prices that way. One could have every *system* have its own separate economy, which varied over time according to events, what the player had previously traded, ''etc. etc.'' to produce something comparable to Elite Dangerous' economic sim, if that's the route one wanted to go down. Obviously the more complexity one adds the harder it gets to script up, but it's now all possible.

[[File:SOTL Altmap F8.png|thumb|right|200px|SOTL Altmap F8 commodities market]]
[[SOTL Altmap]] does have an example of it, which basically throws out the original Elite-like algorithm of trade-goods.plist and starts over. It goes *way* beyond just adding a third economy, too.

Basically in SOTL every trade good is tagged in the trade-goods.plist with a bunch of classes
''e.g.''
classes = ("sotl-ex-salvage","sotl-im-refining","sotl-quantity-high","sotl-priceband-3","sotl-demand-medium","sotl-supply-medium","sotl-volatility-low");
So that means:
- exported by salvage economies
- imported by refining economies
- high quantity, moderate price, low price volatility

Then the market script uses those classes, rather than the standard pricing variables, to define the economic behaviour.
:So line 69-74ish: get the current economy description, convert that to the format used in the class name
:...line 85-90: check for the import and export classes for that economy and see if it's imported or exported
:...lines 100-120: apply various special conditions, so e.g. the sotl-ims-radiation class checks the planet surface radiation levels (custom property in sysinfo) and if the radiation level is high, imports these goods even if the basic economy isn't interested (e.g. "sotl-ceramics-ind" in the plist)
:...and then it uses those calculations (and a bunch more of the classes) in the rest of the script to set the price and quantity depending on whether it's an import, an export, or neither

That's massive overkill for just adding a third mining economy, but one would need to work on a similar principle.

:1) Tag every commodity with classes for (import|export|none)-(agricultural|industrial|mining) as appropriate
:2) Adjust the economy names (there are a few different ways one could do that) so that the 8 economy IDs were allocated to agricultural, industrial and mining economies
:3) Have a price script which like the SOTL one gets the current economy, looks at the classes list to find out if the commodity is imported or exported or neither, and sets the price and quantity accordingly. One could use the standard price_economic, price_average, price_random properties in the plist to give baseline data to the script if one was not planning to do anything too weird.

{Technically one doesn't need the classes - just have the price script contain a list of goods internally for each economy - but this way if other people add extra trade goods in their own OXPs, they can tag them up for mining economy support too}

All fairly straightforward theoretically.

''The biggest impediment to doing a wholesale reworking of the economic system, is just how incompatible it makes lots and lots of OXP's. In order to override the vanilla commodities as in SOTL, requires setting a script for each in trade-goods.plist. Which is fine if it's the only OXP that wants to play around with commodity prices. As soon as two OXP's try to do the same thing, one gets a conflict and no longer knows which OXP pricing model is in play.''

''For SOTL it's fine, because it uses the scenario system to forcibly eject all other OXP's from use while it's running. But if one wants the OXP to go in the general playing pool set of OXP's, it becomes much more complicated. [[User:Phkb|Phkb]] spent a long time trying to work out why his market script wasn't running, only to find that [[UPS Courier]] was quietly adjusting the markets in certain systems via the planetinfo.plist file. And there are a lot of OXP's that want to play in this space, tweaking prices up or down.''

''Hence one usually abandons using any of the script options, and just tweaks the price after all the scripts have finished playing, ''eg'' in [[Smugglers]]. It was the only way to guarantee getting some sort of bump in a price when wanted.''

== Links ==
*[[Oolite JavaScript Reference: Market Scripts]]
*[[Commodities.plist]] - the precursor (which still mostly works!). If it doesn't see [https://bb.oolite.space/viewtopic.php?p=246145#p246145 here] (2015)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16828 Proposal for 1.82: support for economic changes] ([[User:Cim|Cim]], 2014)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16735 Cim on introducing the Trade-goods.plist and deprecating the commodities.plist] (2014)
{{QuoteText|Text=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.|Source=([https://bb.oolite.space/viewtopic.php?p=226722#p226722 Cim in Progress Thread (2014)])}}
=== Using the Trade-goods.plist ===
*[https://bb.oolite.space/viewtopic.php?f=4&t=20576 How to get the displayName for a commodity in the Main Station Market?] (2020)
*[https://bb.oolite.space/viewtopic.php?f=6&t=17269 Thinking about Planet Income classification] (2015)

{{QuoteText|Text=
In 1.81 this is a lot easier to OXP - you can introduce as many economies as you like, though you are limited to eight economy symbols (so if you wanted lots of economy types, you might end up with Poor Industrial, Avg Industrial and Rich Industrial sharing a symbol on the map). The trade good pricing scripts can then be used to set up different price categories in different economies (and introduce additional trade goods, or split an existing good into multiple categories, which may be necessary if you're adding more economies).

Resetting economies across the planets is a big change in terms of lines of code, but is also very easy to automate. If OXPers are looking for a scripting tool to use for this sort of automation, then NodeJS or io.js is free and also uses Javascript as its language, so you don't need to learn a new one - and may even be able to share code between your build scripts and your OXP, though I haven't tried that yet.|Source=([https://bb.oolite.space/viewtopic.php?f=6&t=17269 Cim in Planet Income thread (2015)])}}

== Preamble ==
To tweak the pricing/availability of commodities in (''eg''.) a station, you need to define the market inside the station's Shipdata.plist - or include a "hook" inside that shipdata.plist to a javascript Oolite Market Script (which allows more complex definitions).

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:

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

== Handlers ==

=== updateGeneralCommodityDefinition ===
{{oolite-method-added|1.81}}
function updateGeneralCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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 = <code>false</code> 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 ===
{{oolite-method-added|1.81}}
function updateLocalCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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.

[https://bb.oolite.space/viewtopic.php?f=4&t=17621#p239979 Here is an example] of how to use this method.

== Links ==

=== Examples ===
*Phkb's update of [[SW_Economy]] (v.3.10) creates new economies for "mining worlds" (hewn out from some low tech poor agricultural worlds) with utterly different price scales for mineral, agricultural & industrial goods, as well as medicine.

''These others will be found at the bottom of the wiki page on the'' [[Trade-goods.plist]].
*Setting an orbital main station's slaves on sale to zero
*Creating an invariant market independent of the local system economy (agricultural/industrial)

Trade-goods (abridged)

2026-06-19T08:23:46Z

Wildeblood:

'''You are probably looking for [[Trade-goods.plist]]''', rather than this page.

== F.A.Q. ==

The goal of this page is to answer these questions:

1. How many different places can market influencers be hiding?

In plists, in market scripts, in station methods in ''any damned script''.

2. Which plists exactly?

At least trade-goods.plist , shipdata.plist , shipdata-overides.plist (sp?), planetinfo.plist

3. Which market scripts exactly?

4. What methods?

== Preamble ==

The trade-goods.plist file defines "trade goods" (commodities/cargo). But, it does not ''e.g.'' remove slaves from a particular station or make them cost twice as much as they do at the main orbital station. To do such things, ''i.e.'' to tweak the pricing/availability of commodities in a particular station, you need to define the market inside that station, either within its [[Shipdata.plist]] or within a [[Oolite_Market_Scripts|market script]] linked from its shipdata.plist.

== Overview ==

The '''trade-goods.plist''' file is a dictionary of dictionaries, with (canonical) commodity names as keys to dictionaries of key-value pairs 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 [[Oolite_JavaScript_Reference:_Manifest#setComment|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 [[Oolite Market Scripts|market script]] for this trade good when calculating main station quantities and prices.

'''Note:''' [https://bb.oolite.space/viewtopic.php?p=235837#p235837 What's the difference between the market script specified in planetinfo.plist and the one called for by trade-goods.plist?] (2015)

=== name ===
A string containing the name of the trade good. This may contain [keys]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 [[Oolite_JavaScript_Reference:_Manifest#setShortComment|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 ==

The primary market is that of the system's main station (''i.e.'' the javascript object system.mainStation.market ) Secondary markets are other markets, which are influenced by the primary market, ''e.g.'' that of a local Rock Hermit, or a visiting liner or another orbital station. Both quantities and prices will be influenced by those of the primary market. Needless to say, the primary market is randomly recalculated each time the system is visited.

Secondary market definitions are entered in the [[shipdata.plist#market_definition|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''':

# The market definition array is searched from top to bottom for the first element matching the trade good
# The market quantity is scaled in proportion to the relative capacities for that good in the two markets.
# 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|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 [[shipdata.plist#market_capacity|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 [[shipdata.plist#market_monitored|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.

=== Links ===
*[https://bb.oolite.space/viewtopic.php?f=2&t=21512 Secondary Market Definitions Defined] (2023)

== 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 for determining markets for new stations.

=== From the vanilla game: Rock Hermits ===
The "market_definition" 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: the Trade-goods.plist updated from the original 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;
};

}
=== A new commodity (from the trade-goods.plist inside "SW Economy") ===
"medicine" = {
"name" = "[commodity-name medicine]";
"classes" = ("oolite-consumer","oolite-medical");
"quantity_unit" = 1;
"peak_export" = 7;
"peak_import" = 0;
"price_average" = 640;
"price_economic" = 0.25;
"price_random" = 0.15;
"quantity_average" = 5;
"quantity_economic" = 1.5;
"quantity_random" = 1.0;
"legality_export" = 0;
"legality_import" = 0;
"trumble_opinion" = 0.50;
"sort_order" = 500;
"comment" = "[oolite-commodity-medicine]";
};

=== Setting an orbital main station's slaves on sale to zero ===
[[User:Phkb|Phkb]] provided this example which requires a ''planetinfo.plist'' & a new ''.js file'' - there are other ways to achieve the same result
==== 1) planetinfo.plist (to invoke the market script) ====
(in the "Config" folder)

{
"0 96" = {market_script = "digebiti_noslaves.js";};
}

==== 2) Market script: digebiti_noslaves.js ====
(in the "Scripts" folder) - note the complex name, which prevents confusion with other snippets of script

"use strict";
this.name = "digebiti_noslaves";
this.author = "Phkb";
this.copyright = "(C) 2022 Phkb";
this.licence = "CC-NC-by-SA 4.0";
this.description = "Removes slaves for sale in Digebiti";
this.version = "1.0";

this.updateLocalCommodityDefinition = function(goodDefinition, station, systemID) {
if (goodDefinition.key == "slaves" && station && station.isMainStation) {
goodDefinition.quantity = 0;
}
return goodDefinition;
}

This method will work, so long as no other OXP changes the market_script property of the Digebiti system in the same way.

=== Creating an invariant market independent of the local system economy (agricultural/industrial) ===
If you just use a market_definition in shipdata.plist for the station, then you're merely setting variations on the primary system market.

If you want the station prices to be independent of (or more loosely tied to) the system it's in, then you need to use a [[Oolite_Market_Scripts|market script]].

So what you'd have is something like this - let's say it's a hydroponics station, so it always sells food and nothing else, regardless of whether the general system economy is industrial or agricultural:

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.key == "food") {
// are we calculating the basic Oolite "food" trade good right now? If yes, set our own static prices
goodDefinition.price = 25; // 2.5 credits
goodDefinition.quantity = 80; // lots of food
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

Now ... the reason that market definitions are preferred to be mutators of the system economy is for two reasons.
1) it means you can avoid the situation where you end up with two adjacent stations with wildly different prices ... but you can of course handle that in other ways too, station positioning, restricted access, ''etc''.
2) it makes it easier to handle OXP trade goods:
- other OXPs might have added more "food" type goods, ''e.g.'' "Meat" or "Cheese"
- you can learn about those and handle them specifically

} else if (goodDefinition.key == "bobsfoodoxp_cheese") {
// set price and quantity here

... but that means a lot of keeping up with what everyone else is doing with custom goods.

The idea was that for your hydroponics station what you might do instead is something like this

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So now if another OXP adds Cheese, provided they declare it as "edible", your station will sell it in high quantities at a big discount, but you don't need to know exactly what the baseline price or quantity was set - so if a food-focused OXP was to add "Wine", "Fine Wine" and "Vintage Wine" at a range of prices and quantities, you'd be automatically handling those in reasonable line with a combination of the Wine OXP's basic pricing structure and your station OXP's "food primary source market" style, without necessarily needing to know about every future Wine OXP there might be and explicitly set compatibility.

Note in this example we're still zeroing out all non-food goods - OXP included! - regardless of the local economy. Maybe at this point we'd want to include and document a "hydroponicsoxp-agriculturalequipment" trade good class that other OXPs could use, which this station would buy up at higher demand and prices than normal.

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else if (goodDefinition.classes.indexOf("hydroponicsoxp-agriculturalequipment") >= 0) {
// custom class for other OXPs to add specific agricultural equipment e.g. combine harvesters, compost, fertiliser
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.capacity = 16; // buy a small amount only // TODO: raise capacity if price per tonne is low
goodDefinition.quantity = 0; // not selling this
} else if (goodDefinition.key == "machinery") {
// the basic Oolite Machinery commodity isn't in the custom class but we need to buy something if
// no OXPs adding it are installed
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.quantity = 0; // not selling
goodDefinition.capacity = 16; // small capacity to buy
} else {
// don't buy or sell any other commodity
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So you can see this one has a mix of using, mutating and overruling the definitions set by the system market and OXP commodity definitions ... with this method you could have a whole bunch of OXPs setting up themed stations, and a whole different bunch adding their own custom commodities, and they'd barely have to know about each other to ensure reasonable consistency and compatibility from someone installing any combination of them. (- by [[User:Cim|Cim]], 2023)

Note: this gives examples for 1 commodity at a time, but not how to easily do that for ALL the commodities on ALL the extra stations in a system.

== Using the trade-goods.plist ==
The trade-goods.plist was designed to make commodities simpler, by:
:1) Making it a dictionary rather than an unlabelled array so one could tell which parameter was which
:2) Making the price range for a trade good dependent on more sensible variables, so rather than setting the price range with a bitmask, one set the price and quantity variations dependent on the economy and on random chance.

Compare the v.1.81 trade-goods.plist with a v.1.80 commodities.plist - they were designed to give near-identical market behaviour for the built-in trade goods.

But - that only made it more comprehensible. It didn't really let one do anything particularly different to Elite 84 markets - mostly including the "Rich Industrial -> Poor Agricultural" single spectrum. One can tweak that a bit with peak_export and peak_import to get slightly different shapes (so a good might peak at Poor Industrial rather than Rich Industrial) but it doesn't really give one the option of a third economy type still.

''So how does one introduce a new economic pole, such as a mining industry?''

For that, one needs the scripting support. [[Oolite JavaScript Reference: Market Scripts]]. 
One can quite literally do whatever one likes with the prices that way. One could have every *system* have its own separate economy, which varied over time according to events, what the player had previously traded, ''etc. etc.'' to produce something comparable to Elite Dangerous' economic sim, if that's the route one wanted to go down. Obviously the more complexity one adds the harder it gets to script up, but it's now all possible.

[[File:SOTL Altmap F8.png|thumb|right|200px|SOTL Altmap F8 commodities market]]
[[SOTL Altmap]] does have an example of it, which basically throws out the original Elite-like algorithm of trade-goods.plist and starts over. It goes *way* beyond just adding a third economy, too.

Basically in SOTL every trade good is tagged in the trade-goods.plist with a bunch of classes
''e.g.''
classes = ("sotl-ex-salvage","sotl-im-refining","sotl-quantity-high","sotl-priceband-3","sotl-demand-medium","sotl-supply-medium","sotl-volatility-low");
So that means:
- exported by salvage economies
- imported by refining economies
- high quantity, moderate price, low price volatility

Then the market script uses those classes, rather than the standard pricing variables, to define the economic behaviour.
:So line 69-74ish: get the current economy description, convert that to the format used in the class name
:...line 85-90: check for the import and export classes for that economy and see if it's imported or exported
:...lines 100-120: apply various special conditions, so e.g. the sotl-ims-radiation class checks the planet surface radiation levels (custom property in sysinfo) and if the radiation level is high, imports these goods even if the basic economy isn't interested (e.g. "sotl-ceramics-ind" in the plist)
:...and then it uses those calculations (and a bunch more of the classes) in the rest of the script to set the price and quantity depending on whether it's an import, an export, or neither

That's massive overkill for just adding a third mining economy, but one would need to work on a similar principle.

:1) Tag every commodity with classes for (import|export|none)-(agricultural|industrial|mining) as appropriate
:2) Adjust the economy names (there are a few different ways one could do that) so that the 8 economy IDs were allocated to agricultural, industrial and mining economies
:3) Have a price script which like the SOTL one gets the current economy, looks at the classes list to find out if the commodity is imported or exported or neither, and sets the price and quantity accordingly. One could use the standard price_economic, price_average, price_random properties in the plist to give baseline data to the script if one was not planning to do anything too weird.

{Technically one doesn't need the classes - just have the price script contain a list of goods internally for each economy - but this way if other people add extra trade goods in their own OXPs, they can tag them up for mining economy support too}

All fairly straightforward theoretically.

''The biggest impediment to doing a wholesale reworking of the economic system, is just how incompatible it makes lots and lots of OXP's. In order to override the vanilla commodities as in SOTL, requires setting a script for each in trade-goods.plist. Which is fine if it's the only OXP that wants to play around with commodity prices. As soon as two OXP's try to do the same thing, one gets a conflict and no longer knows which OXP pricing model is in play.''

''For SOTL it's fine, because it uses the scenario system to forcibly eject all other OXP's from use while it's running. But if one wants the OXP to go in the general playing pool set of OXP's, it becomes much more complicated. [[User:Phkb|Phkb]] spent a long time trying to work out why his market script wasn't running, only to find that [[UPS Courier]] was quietly adjusting the markets in certain systems via the planetinfo.plist file. And there are a lot of OXP's that want to play in this space, tweaking prices up or down.''

''Hence one usually abandons using any of the script options, and just tweaks the price after all the scripts have finished playing, ''eg'' in [[Smugglers]]. It was the only way to guarantee getting some sort of bump in a price when wanted.''

== Links ==
*[[Oolite JavaScript Reference: Market Scripts]]
*[[Commodities.plist]] - the precursor (which still mostly works!). If it doesn't see [https://bb.oolite.space/viewtopic.php?p=246145#p246145 here] (2015)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16828 Proposal for 1.82: support for economic changes] ([[User:Cim|Cim]], 2014)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16735 Cim on introducing the Trade-goods.plist and deprecating the commodities.plist] (2014)
{{QuoteText|Text=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.|Source=([https://bb.oolite.space/viewtopic.php?p=226722#p226722 Cim in Progress Thread (2014)])}}
=== Using the Trade-goods.plist ===
*[https://bb.oolite.space/viewtopic.php?f=4&t=20576 How to get the displayName for a commodity in the Main Station Market?] (2020)
*[https://bb.oolite.space/viewtopic.php?f=6&t=17269 Thinking about Planet Income classification] (2015)

{{QuoteText|Text=
In 1.81 this is a lot easier to OXP - you can introduce as many economies as you like, though you are limited to eight economy symbols (so if you wanted lots of economy types, you might end up with Poor Industrial, Avg Industrial and Rich Industrial sharing a symbol on the map). The trade good pricing scripts can then be used to set up different price categories in different economies (and introduce additional trade goods, or split an existing good into multiple categories, which may be necessary if you're adding more economies).

Resetting economies across the planets is a big change in terms of lines of code, but is also very easy to automate. If OXPers are looking for a scripting tool to use for this sort of automation, then NodeJS or io.js is free and also uses Javascript as its language, so you don't need to learn a new one - and may even be able to share code between your build scripts and your OXP, though I haven't tried that yet.|Source=([https://bb.oolite.space/viewtopic.php?f=6&t=17269 Cim in Planet Income thread (2015)])}}

== Preamble ==
To tweak the pricing/availability of commodities in (''eg''.) a station, you need to define the market inside the station's Shipdata.plist - or include a "hook" inside that shipdata.plist to a javascript Oolite Market Script (which allows more complex definitions).

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:

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

== Handlers ==

=== updateGeneralCommodityDefinition ===
{{oolite-method-added|1.81}}
function updateGeneralCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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 = <code>false</code> 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 ===
{{oolite-method-added|1.81}}
function updateLocalCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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.

[https://bb.oolite.space/viewtopic.php?f=4&t=17621#p239979 Here is an example] of how to use this method.

== Links ==

=== Examples ===
*Phkb's update of [[SW_Economy]] (v.3.10) creates new economies for "mining worlds" (hewn out from some low tech poor agricultural worlds) with utterly different price scales for mineral, agricultural & industrial goods, as well as medicine.

''These others will be found at the bottom of the wiki page on the'' [[Trade-goods.plist]].
*Setting an orbital main station's slaves on sale to zero
*Creating an invariant market independent of the local system economy (agricultural/industrial)

Trade-goods (abridged)

2026-06-19T08:09:35Z

Wildeblood: /* Secondary Market Definitions */

[[File:SOTL Altmap F8.png|thumb|right|300px|The ''first'' page of commodities from [[SOTL Altmap]], Cim's 2014 experimental scenario]]
'''You are probably looking for [[Trade-goods.plist]]''', rather than this page.

== Preamble ==

The trade-goods.plist file defines "trade goods" (commodities/cargo). But, it does not ''e.g.'' remove slaves from a particular station or make them cost twice as much as they do at the main orbital station. To do such things, ''i.e.'' to tweak the pricing/availability of commodities in a particular station, you need to define the market inside that station, either within its [[Shipdata.plist]] or within a [[Oolite_Market_Scripts|market script]] linked from its shipdata.plist.

== Overview ==

The '''trade-goods.plist''' file is a dictionary of dictionaries, with (canonical) commodity names as keys to dictionaries of key-value pairs 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 [[Oolite_JavaScript_Reference:_Manifest#setComment|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 [[Oolite Market Scripts|market script]] for this trade good when calculating main station quantities and prices.

'''Note:''' [https://bb.oolite.space/viewtopic.php?p=235837#p235837 What's the difference between the market script specified in planetinfo.plist and the one called for by trade-goods.plist?] (2015)

=== name ===
A string containing the name of the trade good. This may contain [keys]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 [[Oolite_JavaScript_Reference:_Manifest#setShortComment|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 ==

The primary market is that of the system's main station (''i.e.'' the javascript object system.mainStation.market ) Secondary markets are other markets, which are influenced by the primary market, ''e.g.'' that of a local Rock Hermit, or a visiting liner or another orbital station. Both quantities and prices will be influenced by those of the primary market. Needless to say, the primary market is randomly recalculated each time the system is visited.

Secondary market definitions are entered in the [[shipdata.plist#market_definition|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''':

# The market definition array is searched from top to bottom for the first element matching the trade good
# The market quantity is scaled in proportion to the relative capacities for that good in the two markets.
# 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|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 [[shipdata.plist#market_capacity|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 [[shipdata.plist#market_monitored|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.

=== Links ===
*[https://bb.oolite.space/viewtopic.php?f=2&t=21512 Secondary Market Definitions Defined] (2023)

== 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 for determining markets for new stations.

=== From the vanilla game: Rock Hermits ===
The "market_definition" 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: the Trade-goods.plist updated from the original 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;
};

}
=== A new commodity (from the trade-goods.plist inside "SW Economy") ===
"medicine" = {
"name" = "[commodity-name medicine]";
"classes" = ("oolite-consumer","oolite-medical");
"quantity_unit" = 1;
"peak_export" = 7;
"peak_import" = 0;
"price_average" = 640;
"price_economic" = 0.25;
"price_random" = 0.15;
"quantity_average" = 5;
"quantity_economic" = 1.5;
"quantity_random" = 1.0;
"legality_export" = 0;
"legality_import" = 0;
"trumble_opinion" = 0.50;
"sort_order" = 500;
"comment" = "[oolite-commodity-medicine]";
};

=== Setting an orbital main station's slaves on sale to zero ===
[[User:Phkb|Phkb]] provided this example which requires a ''planetinfo.plist'' & a new ''.js file'' - there are other ways to achieve the same result
==== 1) planetinfo.plist (to invoke the market script) ====
(in the "Config" folder)

{
"0 96" = {market_script = "digebiti_noslaves.js";};
}

==== 2) Market script: digebiti_noslaves.js ====
(in the "Scripts" folder) - note the complex name, which prevents confusion with other snippets of script

"use strict";
this.name = "digebiti_noslaves";
this.author = "Phkb";
this.copyright = "(C) 2022 Phkb";
this.licence = "CC-NC-by-SA 4.0";
this.description = "Removes slaves for sale in Digebiti";
this.version = "1.0";

this.updateLocalCommodityDefinition = function(goodDefinition, station, systemID) {
if (goodDefinition.key == "slaves" && station && station.isMainStation) {
goodDefinition.quantity = 0;
}
return goodDefinition;
}

This method will work, so long as no other OXP changes the market_script property of the Digebiti system in the same way.

=== Creating an invariant market independent of the local system economy (agricultural/industrial) ===
If you just use a market_definition in shipdata.plist for the station, then you're merely setting variations on the primary system market.

If you want the station prices to be independent of (or more loosely tied to) the system it's in, then you need to use a [[Oolite_Market_Scripts|market script]].

So what you'd have is something like this - let's say it's a hydroponics station, so it always sells food and nothing else, regardless of whether the general system economy is industrial or agricultural:

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.key == "food") {
// are we calculating the basic Oolite "food" trade good right now? If yes, set our own static prices
goodDefinition.price = 25; // 2.5 credits
goodDefinition.quantity = 80; // lots of food
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

Now ... the reason that market definitions are preferred to be mutators of the system economy is for two reasons.
1) it means you can avoid the situation where you end up with two adjacent stations with wildly different prices ... but you can of course handle that in other ways too, station positioning, restricted access, ''etc''.
2) it makes it easier to handle OXP trade goods:
- other OXPs might have added more "food" type goods, ''e.g.'' "Meat" or "Cheese"
- you can learn about those and handle them specifically

} else if (goodDefinition.key == "bobsfoodoxp_cheese") {
// set price and quantity here

... but that means a lot of keeping up with what everyone else is doing with custom goods.

The idea was that for your hydroponics station what you might do instead is something like this

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So now if another OXP adds Cheese, provided they declare it as "edible", your station will sell it in high quantities at a big discount, but you don't need to know exactly what the baseline price or quantity was set - so if a food-focused OXP was to add "Wine", "Fine Wine" and "Vintage Wine" at a range of prices and quantities, you'd be automatically handling those in reasonable line with a combination of the Wine OXP's basic pricing structure and your station OXP's "food primary source market" style, without necessarily needing to know about every future Wine OXP there might be and explicitly set compatibility.

Note in this example we're still zeroing out all non-food goods - OXP included! - regardless of the local economy. Maybe at this point we'd want to include and document a "hydroponicsoxp-agriculturalequipment" trade good class that other OXPs could use, which this station would buy up at higher demand and prices than normal.

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else if (goodDefinition.classes.indexOf("hydroponicsoxp-agriculturalequipment") >= 0) {
// custom class for other OXPs to add specific agricultural equipment e.g. combine harvesters, compost, fertiliser
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.capacity = 16; // buy a small amount only // TODO: raise capacity if price per tonne is low
goodDefinition.quantity = 0; // not selling this
} else if (goodDefinition.key == "machinery") {
// the basic Oolite Machinery commodity isn't in the custom class but we need to buy something if
// no OXPs adding it are installed
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.quantity = 0; // not selling
goodDefinition.capacity = 16; // small capacity to buy
} else {
// don't buy or sell any other commodity
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So you can see this one has a mix of using, mutating and overruling the definitions set by the system market and OXP commodity definitions ... with this method you could have a whole bunch of OXPs setting up themed stations, and a whole different bunch adding their own custom commodities, and they'd barely have to know about each other to ensure reasonable consistency and compatibility from someone installing any combination of them. (- by [[User:Cim|Cim]], 2023)

Note: this gives examples for 1 commodity at a time, but not how to easily do that for ALL the commodities on ALL the extra stations in a system.

== Using the trade-goods.plist ==
The trade-goods.plist was designed to make commodities simpler, by:
:1) Making it a dictionary rather than an unlabelled array so one could tell which parameter was which
:2) Making the price range for a trade good dependent on more sensible variables, so rather than setting the price range with a bitmask, one set the price and quantity variations dependent on the economy and on random chance.

Compare the v.1.81 trade-goods.plist with a v.1.80 commodities.plist - they were designed to give near-identical market behaviour for the built-in trade goods.

But - that only made it more comprehensible. It didn't really let one do anything particularly different to Elite 84 markets - mostly including the "Rich Industrial -> Poor Agricultural" single spectrum. One can tweak that a bit with peak_export and peak_import to get slightly different shapes (so a good might peak at Poor Industrial rather than Rich Industrial) but it doesn't really give one the option of a third economy type still.

''So how does one introduce a new economic pole, such as a mining industry?''

For that, one needs the scripting support. [[Oolite JavaScript Reference: Market Scripts]]. 
One can quite literally do whatever one likes with the prices that way. One could have every *system* have its own separate economy, which varied over time according to events, what the player had previously traded, ''etc. etc.'' to produce something comparable to Elite Dangerous' economic sim, if that's the route one wanted to go down. Obviously the more complexity one adds the harder it gets to script up, but it's now all possible.

[[File:SOTL Altmap F8.png|thumb|right|200px|SOTL Altmap F8 commodities market]]
[[SOTL Altmap]] does have an example of it, which basically throws out the original Elite-like algorithm of trade-goods.plist and starts over. It goes *way* beyond just adding a third economy, too.

Basically in SOTL every trade good is tagged in the trade-goods.plist with a bunch of classes
''e.g.''
classes = ("sotl-ex-salvage","sotl-im-refining","sotl-quantity-high","sotl-priceband-3","sotl-demand-medium","sotl-supply-medium","sotl-volatility-low");
So that means:
- exported by salvage economies
- imported by refining economies
- high quantity, moderate price, low price volatility

Then the market script uses those classes, rather than the standard pricing variables, to define the economic behaviour.
:So line 69-74ish: get the current economy description, convert that to the format used in the class name
:...line 85-90: check for the import and export classes for that economy and see if it's imported or exported
:...lines 100-120: apply various special conditions, so e.g. the sotl-ims-radiation class checks the planet surface radiation levels (custom property in sysinfo) and if the radiation level is high, imports these goods even if the basic economy isn't interested (e.g. "sotl-ceramics-ind" in the plist)
:...and then it uses those calculations (and a bunch more of the classes) in the rest of the script to set the price and quantity depending on whether it's an import, an export, or neither

That's massive overkill for just adding a third mining economy, but one would need to work on a similar principle.

:1) Tag every commodity with classes for (import|export|none)-(agricultural|industrial|mining) as appropriate
:2) Adjust the economy names (there are a few different ways one could do that) so that the 8 economy IDs were allocated to agricultural, industrial and mining economies
:3) Have a price script which like the SOTL one gets the current economy, looks at the classes list to find out if the commodity is imported or exported or neither, and sets the price and quantity accordingly. One could use the standard price_economic, price_average, price_random properties in the plist to give baseline data to the script if one was not planning to do anything too weird.

{Technically one doesn't need the classes - just have the price script contain a list of goods internally for each economy - but this way if other people add extra trade goods in their own OXPs, they can tag them up for mining economy support too}

All fairly straightforward theoretically.

''The biggest impediment to doing a wholesale reworking of the economic system, is just how incompatible it makes lots and lots of OXP's. In order to override the vanilla commodities as in SOTL, requires setting a script for each in trade-goods.plist. Which is fine if it's the only OXP that wants to play around with commodity prices. As soon as two OXP's try to do the same thing, one gets a conflict and no longer knows which OXP pricing model is in play.''

''For SOTL it's fine, because it uses the scenario system to forcibly eject all other OXP's from use while it's running. But if one wants the OXP to go in the general playing pool set of OXP's, it becomes much more complicated. [[User:Phkb|Phkb]] spent a long time trying to work out why his market script wasn't running, only to find that [[UPS Courier]] was quietly adjusting the markets in certain systems via the planetinfo.plist file. And there are a lot of OXP's that want to play in this space, tweaking prices up or down.''

''Hence one usually abandons using any of the script options, and just tweaks the price after all the scripts have finished playing, ''eg'' in [[Smugglers]]. It was the only way to guarantee getting some sort of bump in a price when wanted.''

== Links ==
*[[Oolite JavaScript Reference: Market Scripts]]
*[[Commodities.plist]] - the precursor (which still mostly works!). If it doesn't see [https://bb.oolite.space/viewtopic.php?p=246145#p246145 here] (2015)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16828 Proposal for 1.82: support for economic changes] ([[User:Cim|Cim]], 2014)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16735 Cim on introducing the Trade-goods.plist and deprecating the commodities.plist] (2014)
{{QuoteText|Text=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.|Source=([https://bb.oolite.space/viewtopic.php?p=226722#p226722 Cim in Progress Thread (2014)])}}
=== Using the Trade-goods.plist ===
*[https://bb.oolite.space/viewtopic.php?f=4&t=20576 How to get the displayName for a commodity in the Main Station Market?] (2020)
*[https://bb.oolite.space/viewtopic.php?f=6&t=17269 Thinking about Planet Income classification] (2015)

{{QuoteText|Text=
In 1.81 this is a lot easier to OXP - you can introduce as many economies as you like, though you are limited to eight economy symbols (so if you wanted lots of economy types, you might end up with Poor Industrial, Avg Industrial and Rich Industrial sharing a symbol on the map). The trade good pricing scripts can then be used to set up different price categories in different economies (and introduce additional trade goods, or split an existing good into multiple categories, which may be necessary if you're adding more economies).

Resetting economies across the planets is a big change in terms of lines of code, but is also very easy to automate. If OXPers are looking for a scripting tool to use for this sort of automation, then NodeJS or io.js is free and also uses Javascript as its language, so you don't need to learn a new one - and may even be able to share code between your build scripts and your OXP, though I haven't tried that yet.|Source=([https://bb.oolite.space/viewtopic.php?f=6&t=17269 Cim in Planet Income thread (2015)])}}

== Preamble ==
To tweak the pricing/availability of commodities in (''eg''.) a station, you need to define the market inside the station's Shipdata.plist - or include a "hook" inside that shipdata.plist to a javascript Oolite Market Script (which allows more complex definitions).

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:

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

== Handlers ==

=== updateGeneralCommodityDefinition ===
{{oolite-method-added|1.81}}
function updateGeneralCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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 = <code>false</code> 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 ===
{{oolite-method-added|1.81}}
function updateLocalCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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.

[https://bb.oolite.space/viewtopic.php?f=4&t=17621#p239979 Here is an example] of how to use this method.

== Links ==

=== Examples ===
*Phkb's update of [[SW_Economy]] (v.3.10) creates new economies for "mining worlds" (hewn out from some low tech poor agricultural worlds) with utterly different price scales for mineral, agricultural & industrial goods, as well as medicine.

''These others will be found at the bottom of the wiki page on the'' [[Trade-goods.plist]].
*Setting an orbital main station's slaves on sale to zero
*Creating an invariant market independent of the local system economy (agricultural/industrial)

OXP howto

2026-06-19T01:57:30Z

Wildeblood: /* Asking AI to write a script for you */ Now hopelessly out of date.

:''Shortcut: EW:OXP and EW:HOWDS redirect here''
[[Image:oolite-oxp-icon.png|100px|thumb|right|OXP icon]]
[[File:Oolite-debug-menu.png|thumb|right|Debug Menu (From the AppleMac variety of the "Oolite TR" version)]]
==Overview==
An '''Oolite Expansion Pack''' can cause many big changes or additions to Oolite's gameplay, or it may represent just a small, subtle alteration. By first appearances, there is no way to tell what is inside, as it's merely a ''folder'' with the added extension '''.oxp'''.
Oolite Version 1.79 onwards supports also compressed files in ZIP format with extension '''.oxz'''.

To learn starting with a non-compressed version have a look at [[OXP_tutorial]].

{{QuoteText|Text=It's worth saying I think that compared with a lot of game addon architectures, the OXP architecture as designed by Giles is already very good at avoiding conflicts compared with a lot of other games
- you can save your game, add, remove and upgrade lots of OXPs, load your game, and have it work
- you can do this repeatedly, while incrementally upgrading the core game, for years
- as a player you basically never have to care about load order; as an OXP developer, rarely

It's also worth noting that a lot of types of OXP conflicts are inevitable due to resource conflicts - a planet can only have one diffuse map, a ship can only have one AI - or due to conceptual conflicts - OXP A removes all stations from a system; OXP B expects the player to dock there.|Source=([https://bb.oolite.space/viewtopic.php?p=241733#p241733 Cim (3rd Lead Developer)])}}

=== Oolite TR version ===
The Oolite Developer Release/Test Release version is specially developed for testing out OXPs. It comes with a [[Debug OXP]]/Debug Console allowing one to spawn ships/station on demand, award oneself a test ship, detect the mass of another ship ''etc''.

It is downloaded from the main Oolite website - currently http://www.oolite.space/download/

== OXZ ==
The new OXZ distribution format is strongly recommended. It makes version control and distribution just so much easier.

To make an OXZ file, use a ZIP program to compress the contents of the OXP folder, so that the [[manifest.plist]] file is in the root of the ZIP file, and the folders (AI, Config, etc) are folders in the ZIP file. Then, rename the ZIP file so that its extension is '''.oxz'''. To inspect an OXZ file, open it with your ZIP program.

Here is a sample: [[Media:X.0.1.oxz]] - just rename all "X" within to the title of your idea and put your name into the author fields.

You can use [http://www.ghisler.com/download.htm Total Commander] or [http://en.wikipedia.org/wiki/Krusader Krusader] to edit files within '''.oxz''' directly, without unpacking.

For more details read [https://bb.oolite.space/viewtopic.php?f=4&t=16688 The All-in-One Guide to OXZ Packaging and Distribution].

=== Creating an .oxz on an AppleMac ===
When you compress the files/folders on the AppleMac to create the .oxz ''do not'' select them with your mouse! This way lies misery!

Rather, ensure the relevant files/folders are inside one overall folder. Then, use '''command-a''' to select all the ''contents'' of this overall folder and then select '''compress''' from the file menu on the finder's menu bar. Finally, rename your newly-created .zip file as an .oxz

==Structure==
Inside the '''.oxp''' folder, or the '''.oxz''' file, it will at least contain a folder (Config, AIs, Models, Textures, etc...) that holds scripts, plists or other things like textures or models. It is down to the goal of the [[OXP]], which ways to combine elements to the OXP's contents. To get a feeling for it, simply take a look in other oxps. (If they are in .oxz format, any normal unzip program can inspect their contents - many will even let you edit the contents without having to unzip and rezip the file)

The structure for OXPs:
AddOns (folder)
~.oxp (really just another folder!) - Holds manifest.plist and the other folders:

--> AIs (folder) - Holds AI plists
--> Config (folder) - Holds all other plists (and possibly an anonymous "Script.js")
--> Images (folder) - Holds background images
--> Models (folder) - Holds the .dat files (special Oolite format)
--> Music (folder) - Surprise - holds .ogg music files
--> Scenarios (folder) - Holds new game scenarios (v1.79)
--> Scripts (folder) - Holds scripts (worldScripts and shipScripts)
--> Shaders (folder) - Holds Vertex and Fragment shaders (v1.69)
--> Sounds (folder) - Holds sound files
--> Textures (folder) - Holds models textures (can be planets, too!)
--> [[manifest.plist]] (file)
''the following might also be found in here:''
--> [[Misc plists|info.plist]] (file, seems to be a poor duplicate of the Manifest.plist)
--> [[Requires.plist]] (file: deprecated - replaced by Manifest.plist)

*If the OXP is in the uncompressed OXP folder format, the .oxp folder must contain a [[requires.plist]] file. If it is in the compressed OXZ single-file format, it must contain a [[manifest.plist]] file.

*[https://bb.oolite.space/viewtopic.php?f=4&t=13134 Nested OXPs in AddOns folder] (2012) - some OXZ's do this (Station spotter oxp inside [[Stations for Extra Planets]])

===AIs folder===
The folder named AIs contains any AI.plist additions the OXP might use.

* [[OXP howto AI|Making Oolite AI]]

In Oolite 1.79 AIs may be written in Javascript using .js files in this folder. A helper library is provided to make writing complex JS AIs simpler.

* [[Oolite PriorityAI Documentation]]
* [[Oolite PriorityAI Tutorial]]

===Config folder===
All plist files except for those introducing new AIs, ''[[requires.plist]]'', ''[[manifest.plist]]'' or ''[[Misc plists|info.plist]]'', belong in Config.

In its simplest form, an OXP could contain only a Config with an altering ''script.plist'' or ''planetinfo.plist''. An OXP that adds a new ship needs a ''shipdata.plist'' entry, and unless it is based entirely on existing Oolite data, would include a model and texture.

* [[OXP howto plist|Making Oolite plists]]
* Usually irrelevant: The Config folder isn't cached in the same way as the rest of an oxp because usually its contents merge rather than overwriting (See [https://bb.oolite.space/viewtopic.php?f=3&t=16927 here])
 
This folder contains [[Property lists]] such as:

* ''[[characters.plist]]'' that adds non-player characters to Oolite.
* ''[[crosshairs.plist]]'' that contains the look for your weapons (v1.73).
* ''[[customsounds.plist]]'' that contains references to ingame used sounds.
* ''[[descriptions.plist]]'' that adds vocabulary to Oolite texts.
* ''[[effectdata.plist]]'' defines custom visual effects (v1.77).
* ''[[equipment.plist]]'' lists upgrades available from the Shipyard.
* ''[[explosions.plist]]'' customises things blowing up (v1.81)
* ''[[global-settings.plist]]'' sets a few miscellaneous universal settings (v1.81)
* ''[[gui-settings.plist]]'' settings for reformatting the GUI screens (v1.81)
* ''[[hud.plist]]'' and ''[[hud.plist|hud-small.plist]]'' that allows for changes or a radically new ''Head-Up Display''.
* ''[[Oolite_Keyboard_Controls|keyconfig2.plist]]'' that allows for changes of the keymapping.
* ''[[missiontext.plist]]'' contains texts for the mission screens.
* ''[[OXPMessages.plist]]'' adds warnings to testversions of an oxp.
* ''[[planetinfo.plist]]'' that plots system specific changes from the default. May also contain ''script actions''.
* ''[[role-categories.plist]]'' for specifying groups of roles (''eg''.: trader, Miner, pirate ''etc''.) with similar properties (v1.79)
* ''[[scenarios.plist]]'' lists the starting scenarios in the Scenarios folder (v1.79).
* ''[[screenbackgrounds.plist]]'' that contains references to background images (v1.74).
* ''[[Scripting Oolite with JavaScript|script.js]]'' is the successor of [[script.plist]] in JavaScript.It will be loaded in preference to script.plist if both exist.
* ''[[shipdata.plist]]'' that introduces any new entity (ships, stations, objects etc.) to Oolite.
* ''[[shipdata-overrides.plist]]'' that selectively can replace shipentries in other shipdata.plists
* ''[[shiplibrary.plist]]'' that gives information for the ship description library viewable from the startup screen (v1.79)
* ''[[shipyard.plist]]'' that introduces new ships available for player purchase.
* ''[[shipyard-overrides.plist]]'' that selectively can replace shipentries in other shipyard.plists
* ''[[speech_pronunciation_guide.plist]]'' is another of the other custom methods.
* ''[[trade-goods.plist]]'' defines trade goods in 1.81 and later
* ''[[world-scripts.plist]]'' that contains a list of scripts (if more than one worldScript should be used).

Deprecated:
* ''[[commodities.plist]]'' that contains information for each commodity in a market in 1.80 or earlier
* ''[[demoships.plist]]'' that selects demoships to show on startup (replaced - approximately - by shiplibrary.plist in 1.79 and later)
* ''[[illegal_goods.plist]]'' that contains a list of banned/forbidden items in 1.80 or earlier. GalCop has an eye on that.
* ''[[Oolite_Keyboard_Controls|keyconfig.plist]]'' that allows for changes of the keymapping. (deprecated in v1.92)
* ''[[pirate-victim-roles.plist]]'' that defines which roles should act as traders. (deprecated in v1.79)
* ''[[script.plist]]'' to handle conditional ''script actions''. (deprecated)
* ''[[script.oos]]'' was briefly introduced during 1.70 development but is now deprecated in favour of JS.)

=== Models folder===
Oolite models need to be in an Oolite specific format using the the '''.dat''' file extension. There are utilities available that convert models made in Wings 3D (.obj) and Meshwork (.mesh) into this. A .dat file can be opened in a plain text editor to view the object's assigned texture names and see that they correspond with the actual file names in the Textures folder. The .dat file must be named exactly as it is referenced in the shipdata ''model'' entry - case sensitive!!!

* [[OXP howto model|Making Oolite models]] - tutorials for Wings3D & Blender, notes on sub-entities, links ''etc''.
* [https://bb.oolite.space/viewtopic.php?f=4&t=12165 Model Converter utilities] (2012-17)
* Video: [https://bb.oolite.space/viewtopic.php?f=4&t=16123 From scratch to Mamba in under an hour] ([[Dertien]], 2013)

===Scripts folder===
Scripts are in text format. In this folder you can put both JavaScript scripts as well as legacy scripts. New OXPs should only use JavaScript here.
* [[Scripting_Oolite_with_JavaScript|Scripting Oolite with Javascript]]
* [[Oolite_JavaScript_object_model|Scripting reference]]

===Textures folder===

Oolite's textures are in the '''.png''' format, usually at a standard 512x512 size, and must be named exactly as they are named in the .dat file.

* [[OXP howto texture|Making Oolite textures]]

* [[Smivs'_texture_tutorial|Smivs' guide to making Oolite textures]]

* [[Texturing tips and tricks by Theta Seven]]

Viewing a specific texture and / or model in Oolite.
"I made one. How do I proof it?"

* [[Viewing a Texture or Model]]

==Tool: OXP Verifier==

Oolite has what amounts to a spell checker for shipdata.plist and some other plists, called the OXP verifier.

*It does not work with OXZ's (so convert your OXP's to OXZ's later!).
*Nor does it work on the standard game release version of Oolite (v.1.90, v.1.92 ''etc''). Only on the Test Release/Developer's Release version ''and'' on the Nightlies/Pre-Releases (v.1.91, v.1.93 ''etc''.)

The verifier detects unknown keys or wrong use of keys ''etc''. It can currently only be invoked from the command line.

On Windows or Linux:
Code:
'''oolite.app/oolite --verify-oxp <path to OXP> '''

On Mac OS X:
Code:
'''Oolite.app/Contents/MacOS/Oolite --verify-oxp <path to OXP>'''

Most Mac users will not be familiar with using the command line. Look inside your application folder for a '''utilities folder'''. Inside that you will find a program called [https://en.wikipedia.org/wiki/Terminal_(macOS) Terminal]. 
Run it to open a terminal window. Now drop the oolite application on that window. That will generate the path to oolite on the command line. Delete the trailing space and paste the following text - including the trailing space- behind it: "/Contents/MacOS/Oolite --verify-oxp ". Now drop the oxp you want to verify on the window. That will again create the path to the oxp behind the last entry. 
When you select the window and hit the <return> key, the verification will start. It should now open the Console program, showing the results. 
'''Console''' is a log viewer developed by Apple Inc. and included with macOS, also in the utilities folder. It allows users to search through all of the system's logged messages, and can alert the user when certain types of messages are logged. The Console is generally used for troubleshooting when there is a problem with the computer. MacOS itself, as well as any applications that are used, send a constant stream of messages to the system in the form of log files. The console allows you to read the system logs, help find certain ones, monitor them, and filter their contents. See [[Debug OXP]] for more information.

There is a lengthy file - '''OXP verifier design.txt''' tucked inside your Oolite installation with more information about it

Note that it is possible to [https://bb.oolite.space/viewtopic.php?f=2&t=21443 obtain graphical output] from Graphviz for OXP Verifier.

=== Verifier BB threads ===
*[https://bb.oolite.space/viewtopic.php?f=8&t=13400 plist Editor Pro for Windows] (2013 - full of relevant Red Herrings)
*[https://bb.oolite.space/viewtopic.php?f=3&t=16865 lite --verify-oxp fails when path has spaces in it] (2014)
*[https://bb.oolite.space/viewtopic.php?f=4&t=21359 OXP Develoopment and Plist files] (2023 - quick introduction)

=== Correcting with plutil (Apple Macintosh Terminal utility) ===
Since a very small mistake is enough to stop a .plist from being accepted, it's important to be exact about every letter and sign. The Mac Terminal utility has a very practical tool for catching parser errors. After opening Terminal, simply type plutil, add one space, and drag and drop the plist in question onto the Terminal window. This will cause the 'address' of the plist to be shown. Hit return, and Terminal will reveal whether or not the plist is OK. If it's not, you might be given a clue to what is wrong, and the line number of the error - or just a general note that "Unexpected character { at line 1"!

==Need for unique names==
On loading the oxps, Oolite will add all files in the AIs, Models, Sound and Scripts folders in one big folder for its own use. That means that all files need unique names or one file will overwrite another with the same name. Files in Textures are not pre-loaded, but when looking for a specific texture Oolite looks in all Texture folders until it finds a texture file with a matching name. If another oxp contains a texture with identical name, Oolite could use that texture.

For the Config folder something similar happens. Here the plists all have the same name, but the content of all oxp plists is loaded per type in one big plist. e.g. all individual shipData.plist go in one big shipData.plist file. And within a single plist, all keys must be unique. When two plists use the same key, the later loading key will overwrite the former.

Generally it is a good habit to precede your chosen filenames and keys with the name of the oxp, or another unique prefix, to make sure the names stay unique and no other oxp will use the same names.

==Scripting with JavaScript==
Older OXPs (from [[User:Aegidian|Aegidian]]'s day were written in Legacy Script: see [[Methods]]. Modern OXPs are written in JavaScript. Specifically oolite.jsVersion 185, an Oolite specific variant of '''ECMAv5'''. It is the same Spidermonkey version that Firefox 4 shipped with many years ago, but it is a special build for Oolite. This is the version that we have almost always had and it has not changed between versions of the game. [https://bb.oolite.space/viewtopic.php?p=256623#p256623 It is unlikely to change] in the future.

JavaScript is the preferred scripting interface for worldScripts and shipScripts. The legacy scripting interface (see [[script.plist]]) still works, but is not supported. See [[Scripting Oolite with JavaScript]] for more information.

Note that most of the [[Legacy Scripting]] still works perfectly well (XML & OpenStep)!

==Hidden settings==
There are several [[Hidden_Settings_in_Oolite]] that make life for an oxp creator easier. One of them is the setting '''always-flush-cache'''. It makes every startup a bit slower, but it prevents Oolite working with cached data instead of your newly changed file. For someone that only does occasional oxp changes it will be enough to flush the cache by holding the shift key when starting Oolite but if you are writing oxps, this is the way to prevent frustrations.

==Cookbook==
* How to add dials to a HUD: https://bb.oolite.space/viewtopic.php?p=290352#p290352
* How to limit a station's shipyard to only offer a defined set of ships: https://bb.oolite.space/viewtopic.php?p=293174#p293174
* Ship/Station design with external docking ports: https://bb.oolite.space/viewtopic.php?f=4&t=21574&p=293777

== See Also ==
*'''Context''': [https://bb.oolite.space/viewtopic.php?p=275434#p275434 What can OXP's ''not'' change?] (2021)
*It is often helpful to dip one's toes (claws?) in the water by experimenting with tweaking oxp's first: see [[How to tweak OXZ's]]
*[[:Category:Oolite scripting]]
*[[Javascript Operators]]
*[[:Category:Oolite JavaScript Reference‎]]
*[[:Category:Oolite Development]]
*[[User:Montana05|Montana05]] recommends https://www.w3schools.com/js/js_array_sort.asp for better knowledge of the js on Oolite.
*[https://bb.oolite.space/viewtopic.php?f=4&t=12149 OXP Development Best Practices] (2012-7)
*Some older oxp's are written in [[Legacy Scripting]]
*[https://github.com/OoliteProject/oolite/find/master Github] vanilla game code repository - the resources section at the bottom of the page contains possibly useful parts of vanilla game coding, with occasional annotations.
=== Tools ===
*[[List of software]] that is helpful for creating OXPs (eg. editorial packages for javascript or 3D model creators)
*[[List of Planets used in OXPs]] for planets already used by other OXPs. Helps authors avoid overlapping with or breaking other OXPs.
*[[OXP_howto_Game_Balance|OXP howto Game Balance]] to avoid conflicts from accidental gameplay changes.
*[[Long Range Scanner]] is an OXP which allows you to jump around the star system to objects you have placed there - or to jump around within the galaxy. A "cheat" for players, but a useful tool for some OXP designers.

*[https://bb.oolite.space/viewtopic.php?f=4&t=13422 What Tools Are Good For Windows OXP Programming?] (2013)

==== Tutorials for Tools ====
*[https://web.archive.org/web/20050317033938/http://oolite.aegidian.org/cyoship/ Oolite Tutorial - Meshwork Shipbuilding (OSX only)] via WayBack Machine
*[https://web.archive.org/web/20060621211940/http://oolite.aegidian.org/cyoship2/ Oolite Tutorial - Wings 3D Shipbuilding (Cross-platform)] via WayBack Machine

=== OXP tutorials ===
Oolite changes affecting different varieties of OXPs happened with v.1.76 (2011), v.1.80 (2014) & v1.82 (2015).
*[https://bb.oolite.space/viewtopic.php?f=4&t=20937 MasterClass: How to OXP (updating SoThisTC)] by [[User:Spara|Spara]] who teaches computing in Helsinki! (2021)
*[https://archive.org/details/GettingStartedWithOoliteOXZDevelopment Getting started with OXZ Development] ''An .odt for Open Office'': By Bugbear (2012). 2 example OXPs: a pirate-ridden solar systems warning tool & Witchspace Blockades [https://bb.oolite.space/viewtopic.php?f=4&t=17731 BB Thread (2015)]
*[[OXP_tutorial|OXP Tutorial]] creating a new spaceship - and then tweaking it in different ways (2007-13)
*[[OXP howto dockable stations|Creating a dockable station]] (2009-10)
*[[User:Shipbuilder|Shipbuilder]] wrote a Shaders tutorial with resource packs (2013)

*[https://bb.oolite.space/viewtopic.php?f=4&t=18837 OXP Performance] BB thread (mostly 2017-8): improving your OXP (speed, ''etc'')

*[https://bb.oolite.space/viewtopic.php?f=4&t=18284 The bare minimum for a game-recognizable ship OXP] (thread: 2016)
*[https://bb.oolite.space/viewtopic.php?f=4&t=14135 How to make a simple OXP?] (thread: 2013) 3 OXPs - pop-up message at docking, set only Pythons for sale at Lave shipyard, create a new ship.

*[[Escape Pod Locator OXP]] has notes on programming on the bottom of the page regarding beacon transmission & location

=== Helpful OXPs for your OXP===
There are a number of OXPs which have been specifically written to allow your OXP to use them:
*[[Library OXP|Library]]: a collection of useful snippets and helpers. Its main purpose is to simplify or unify some common tasks used by OXPers.
:*It can add dynamic maps, music & animation.
:*It adds a Personal Assistant Device for the player with details of people met, medals awarded, Guild rankings, ''etc''.
:*It allows in-game configuration of an oxp by the player.
:*Add-on modules allows inspection of models and materials for creation of ship & station oxps.
*[[GalCop Missions]] introduces many new pieces of equipment with wide varieties of use (Cargo Stoppers, Ejection Dampers, Range Finders, Solar Radiation Disrupter Missiles, Seismic Resonance Scanners, Patient Transport Modules ''etc''). It can also help with managing missions.
*[[Diplomancy]] can be used to make states of war impact personally on the player
*[[System Data Config]] helps re-organise the F7 screen to squeeze more information onto it

==== While docked/stations ====
*[[HD Backgrounds]] can provide a High Definition screenshot of a station lobby or other such for interaction with the player
*[[BGS]] can help organise a customised docking or launching sequence (see the [[Riredi OXP]] or the [[Kiota Stations]]).
*[[GNN]] can broadcast your news alerts (see how [[Diplomancy]] uses it for war & peace declarations). GNN also contains '''PhraseGen''' which can be used for randomizing text descriptions.
*[[Station Validator]] will remember that a station has been destroyed and stop Oolite automatically replacing it on the next visit to the system
*[[Station Dock Control]] can help interraction with other ships docked at the station
*[[Bulletin Board System]] can help manage interractions at the station
*[[Email System OXP]] can also help manage interractions at the station
*[[Ship Storage Helper]] allows storage of the player's ship whilst doing other things (such as flying another ship!)
*[[Equipment Storage OXP]] allows storage of equipment/goods whilst doing other things
*[[Ship's Library]] allows reading documents with illustrations while docked (see the included Ship's Manual)
*[[Station Options]] allows complex configurations of equipment, but could potentially also be used for managing dialogue with NPCs
*[[Life in the Frontier]] was being expanded to cover more stations (Dodo/Ico/Rock Hermits and potentially OXP stations), but is currently mothballed.

==== In-flight ====
*[[MFD - Broadcast Comms]] can be used for in-flight interaction with NPC's
*[[Bigships]] can be used to help with the AI for massive space ships which cannot dock at orbital stations
*[[Montanas Resource Pack 01]] contains a number of resources for use (treasures, containers, escape/survival equipment)
*[[Star System Lane Indicator]] - the older version contains a very graphical dynamic display (does not function properly, but boy! does it look good!)
*[[SOTL Exploration]] contains exploration equipment and a non-automatic hyperspace jump
*[[SOTL Altmap]] contains different politics, markets and NPCs with Torus Drives.
*[[Resistance Commander]] & [[EscortDeck]] contain mechanisms for "managing" allied ships.

==== Planet Surfaces ====
*[[Planetfall OXP]] allows landing on the planet (used by [[Feudal States]] for access to the Royal Court, and by [[Astronaut]] for space-jumping)
*[[Lave is Earth 8k]] contains night-time city lighting

=== Packaging and distribution ===
*[https://bb.oolite.space/viewtopic.php?f=4&t=16688 The All-in-One Guide to OXZ Packaging and Distribution].
::And see [https://bb.oolite.space/viewtopic.php?p=279034#p279034 this post] for AppleMac issues with the above.
* Cim created [https://github.com/cim--/oxp-build-scripts some scripts to ease packaging] a project.
*[[OXP Distribution]] The All-in-One Guide to OXP Packaging and Distribution (and [[OXP_standards]] for advice on which ways of doing things are supported and which are not).
* Since the domain change to [https://oolite.space] the distribution of expansions has changed slightly. The new version is still subject to discussions and might change again. Here is a [[Publishing Procedure Comparison]].
*[[Gameplay_and_Balance_Indicator|Gameplay Balance Indicator]] and [[OXP_Levelindicators|Difficulty Indicator]]. Add these to your wiki page to show effects on Game Balance and the Difficulty Level of your OXP/OXZ. The '''first''' indicates the impact on play (equipment making the game easier/more difficult), the '''second''' indicates the suggested [[Elite Rating]] needed to attempt the mission/defeat the ship ''etc''.

[[Category:Oolite]]
[[Category:Oolite scripting]]

Trade-goods (abridged)

2026-06-18T16:21:09Z

Wildeblood: /* Using the new Trade-goods.plist */

[[File:SOTL Altmap F8.png|thumb|right|300px|The ''first'' page of commodities from [[SOTL Altmap]], Cim's 2014 experimental scenario]]
'''You are probably looking for [[Trade-goods.plist]]''', rather than this page.

== Preamble ==

The trade-goods.plist file defines "trade goods" (commodities/cargo). But, it does not ''e.g.'' remove slaves from a particular station or make them cost twice as much as they do at the main orbital station. To do such things, ''i.e.'' to tweak the pricing/availability of commodities in a particular station, you need to define the market inside that station, either within its [[Shipdata.plist]] or within a [[Oolite_Market_Scripts|market script]] linked from its shipdata.plist.

== Overview ==

The '''trade-goods.plist''' file is a dictionary of dictionaries, with (canonical) commodity names as keys to dictionaries of key-value pairs 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 [[Oolite_JavaScript_Reference:_Manifest#setComment|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 [[Oolite Market Scripts|market script]] for this trade good when calculating main station quantities and prices.

'''Note:''' [https://bb.oolite.space/viewtopic.php?p=235837#p235837 What's the difference between the market script specified in planetinfo.plist and the one called for by trade-goods.plist?] (2015)

=== name ===
A string containing the name of the trade good. This may contain [keys]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 [[Oolite_JavaScript_Reference:_Manifest#setShortComment|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 ==

The Primary market is that of the main orbital station of the system. The Secondary markets are other station/dockable markets (which are influenced by the primary market), ''eg'' that of a local Rock Hermit, or a visiting liner or another orbital station. Both quantities and prices will be influenced by those of the primary market. Needless to say, the primary market is randomly recalculated each time the system is visited.

Secondary market definitions are entered in the [[shipdata.plist#market_definition|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:

# The market definition array is searched from top to bottom for the first element matching the trade good
# The market quantity is scaled in proportion to the relative capacities for that good in the two markets.
# 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|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 [[shipdata.plist#market_capacity|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 [[shipdata.plist#market_monitored|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.

=== Links ===
*[https://bb.oolite.space/viewtopic.php?f=2&t=21512 Secondary Market Definitions Defined] (2023)

== 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 for determining markets for new stations.

=== From the vanilla game: Rock Hermits ===
The "market_definition" 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: the Trade-goods.plist updated from the original 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;
};

}
=== A new commodity (from the trade-goods.plist inside "SW Economy") ===
"medicine" = {
"name" = "[commodity-name medicine]";
"classes" = ("oolite-consumer","oolite-medical");
"quantity_unit" = 1;
"peak_export" = 7;
"peak_import" = 0;
"price_average" = 640;
"price_economic" = 0.25;
"price_random" = 0.15;
"quantity_average" = 5;
"quantity_economic" = 1.5;
"quantity_random" = 1.0;
"legality_export" = 0;
"legality_import" = 0;
"trumble_opinion" = 0.50;
"sort_order" = 500;
"comment" = "[oolite-commodity-medicine]";
};

=== Setting an orbital main station's slaves on sale to zero ===
[[User:Phkb|Phkb]] provided this example which requires a ''planetinfo.plist'' & a new ''.js file'' - there are other ways to achieve the same result
==== 1) planetinfo.plist (to invoke the market script) ====
(in the "Config" folder)

{
"0 96" = {market_script = "digebiti_noslaves.js";};
}

==== 2) Market script: digebiti_noslaves.js ====
(in the "Scripts" folder) - note the complex name, which prevents confusion with other snippets of script

"use strict";
this.name = "digebiti_noslaves";
this.author = "Phkb";
this.copyright = "(C) 2022 Phkb";
this.licence = "CC-NC-by-SA 4.0";
this.description = "Removes slaves for sale in Digebiti";
this.version = "1.0";

this.updateLocalCommodityDefinition = function(goodDefinition, station, systemID) {
if (goodDefinition.key == "slaves" && station && station.isMainStation) {
goodDefinition.quantity = 0;
}
return goodDefinition;
}

This method will work, so long as no other OXP changes the market_script property of the Digebiti system in the same way.

=== Creating an invariant market independent of the local system economy (agricultural/industrial) ===
If you just use a market_definition in shipdata.plist for the station, then you're merely setting variations on the primary system market.

If you want the station prices to be independent of (or more loosely tied to) the system it's in, then you need to use a [[Oolite_Market_Scripts|market script]].

So what you'd have is something like this - let's say it's a hydroponics station, so it always sells food and nothing else, regardless of whether the general system economy is industrial or agricultural:

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.key == "food") {
// are we calculating the basic Oolite "food" trade good right now? If yes, set our own static prices
goodDefinition.price = 25; // 2.5 credits
goodDefinition.quantity = 80; // lots of food
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

Now ... the reason that market definitions are preferred to be mutators of the system economy is for two reasons.
1) it means you can avoid the situation where you end up with two adjacent stations with wildly different prices ... but you can of course handle that in other ways too, station positioning, restricted access, ''etc''.
2) it makes it easier to handle OXP trade goods:
- other OXPs might have added more "food" type goods, ''e.g.'' "Meat" or "Cheese"
- you can learn about those and handle them specifically

} else if (goodDefinition.key == "bobsfoodoxp_cheese") {
// set price and quantity here

... but that means a lot of keeping up with what everyone else is doing with custom goods.

The idea was that for your hydroponics station what you might do instead is something like this

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So now if another OXP adds Cheese, provided they declare it as "edible", your station will sell it in high quantities at a big discount, but you don't need to know exactly what the baseline price or quantity was set - so if a food-focused OXP was to add "Wine", "Fine Wine" and "Vintage Wine" at a range of prices and quantities, you'd be automatically handling those in reasonable line with a combination of the Wine OXP's basic pricing structure and your station OXP's "food primary source market" style, without necessarily needing to know about every future Wine OXP there might be and explicitly set compatibility.

Note in this example we're still zeroing out all non-food goods - OXP included! - regardless of the local economy. Maybe at this point we'd want to include and document a "hydroponicsoxp-agriculturalequipment" trade good class that other OXPs could use, which this station would buy up at higher demand and prices than normal.

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else if (goodDefinition.classes.indexOf("hydroponicsoxp-agriculturalequipment") >= 0) {
// custom class for other OXPs to add specific agricultural equipment e.g. combine harvesters, compost, fertiliser
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.capacity = 16; // buy a small amount only // TODO: raise capacity if price per tonne is low
goodDefinition.quantity = 0; // not selling this
} else if (goodDefinition.key == "machinery") {
// the basic Oolite Machinery commodity isn't in the custom class but we need to buy something if
// no OXPs adding it are installed
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.quantity = 0; // not selling
goodDefinition.capacity = 16; // small capacity to buy
} else {
// don't buy or sell any other commodity
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So you can see this one has a mix of using, mutating and overruling the definitions set by the system market and OXP commodity definitions ... with this method you could have a whole bunch of OXPs setting up themed stations, and a whole different bunch adding their own custom commodities, and they'd barely have to know about each other to ensure reasonable consistency and compatibility from someone installing any combination of them. (- by [[User:Cim|Cim]], 2023)

Note: this gives examples for 1 commodity at a time, but not how to easily do that for ALL the commodities on ALL the extra stations in a system.

== Using the trade-goods.plist ==
The trade-goods.plist was designed to make commodities simpler, by:
:1) Making it a dictionary rather than an unlabelled array so one could tell which parameter was which
:2) Making the price range for a trade good dependent on more sensible variables, so rather than setting the price range with a bitmask, one set the price and quantity variations dependent on the economy and on random chance.

Compare the v.1.81 trade-goods.plist with a v.1.80 commodities.plist - they were designed to give near-identical market behaviour for the built-in trade goods.

But - that only made it more comprehensible. It didn't really let one do anything particularly different to Elite 84 markets - mostly including the "Rich Industrial -> Poor Agricultural" single spectrum. One can tweak that a bit with peak_export and peak_import to get slightly different shapes (so a good might peak at Poor Industrial rather than Rich Industrial) but it doesn't really give one the option of a third economy type still.

''So how does one introduce a new economic pole, such as a mining industry?''

For that, one needs the scripting support. [[Oolite JavaScript Reference: Market Scripts]]. 
One can quite literally do whatever one likes with the prices that way. One could have every *system* have its own separate economy, which varied over time according to events, what the player had previously traded, ''etc. etc.'' to produce something comparable to Elite Dangerous' economic sim, if that's the route one wanted to go down. Obviously the more complexity one adds the harder it gets to script up, but it's now all possible.

[[File:SOTL Altmap F8.png|thumb|right|200px|SOTL Altmap F8 commodities market]]
[[SOTL Altmap]] does have an example of it, which basically throws out the original Elite-like algorithm of trade-goods.plist and starts over. It goes *way* beyond just adding a third economy, too.

Basically in SOTL every trade good is tagged in the trade-goods.plist with a bunch of classes
''e.g.''
classes = ("sotl-ex-salvage","sotl-im-refining","sotl-quantity-high","sotl-priceband-3","sotl-demand-medium","sotl-supply-medium","sotl-volatility-low");
So that means:
- exported by salvage economies
- imported by refining economies
- high quantity, moderate price, low price volatility

Then the market script uses those classes, rather than the standard pricing variables, to define the economic behaviour.
:So line 69-74ish: get the current economy description, convert that to the format used in the class name
:...line 85-90: check for the import and export classes for that economy and see if it's imported or exported
:...lines 100-120: apply various special conditions, so e.g. the sotl-ims-radiation class checks the planet surface radiation levels (custom property in sysinfo) and if the radiation level is high, imports these goods even if the basic economy isn't interested (e.g. "sotl-ceramics-ind" in the plist)
:...and then it uses those calculations (and a bunch more of the classes) in the rest of the script to set the price and quantity depending on whether it's an import, an export, or neither

That's massive overkill for just adding a third mining economy, but one would need to work on a similar principle.

:1) Tag every commodity with classes for (import|export|none)-(agricultural|industrial|mining) as appropriate
:2) Adjust the economy names (there are a few different ways one could do that) so that the 8 economy IDs were allocated to agricultural, industrial and mining economies
:3) Have a price script which like the SOTL one gets the current economy, looks at the classes list to find out if the commodity is imported or exported or neither, and sets the price and quantity accordingly. One could use the standard price_economic, price_average, price_random properties in the plist to give baseline data to the script if one was not planning to do anything too weird.

{Technically one doesn't need the classes - just have the price script contain a list of goods internally for each economy - but this way if other people add extra trade goods in their own OXPs, they can tag them up for mining economy support too}

All fairly straightforward theoretically.

''The biggest impediment to doing a wholesale reworking of the economic system, is just how incompatible it makes lots and lots of OXP's. In order to override the vanilla commodities as in SOTL, requires setting a script for each in trade-goods.plist. Which is fine if it's the only OXP that wants to play around with commodity prices. As soon as two OXP's try to do the same thing, one gets a conflict and no longer knows which OXP pricing model is in play.''

''For SOTL it's fine, because it uses the scenario system to forcibly eject all other OXP's from use while it's running. But if one wants the OXP to go in the general playing pool set of OXP's, it becomes much more complicated. [[User:Phkb|Phkb]] spent a long time trying to work out why his market script wasn't running, only to find that [[UPS Courier]] was quietly adjusting the markets in certain systems via the planetinfo.plist file. And there are a lot of OXP's that want to play in this space, tweaking prices up or down.''

''Hence one usually abandons using any of the script options, and just tweaks the price after all the scripts have finished playing, ''eg'' in [[Smugglers]]. It was the only way to guarantee getting some sort of bump in a price when wanted.''

== Links ==
*[[Oolite JavaScript Reference: Market Scripts]]
*[[Commodities.plist]] - the precursor (which still mostly works!). If it doesn't see [https://bb.oolite.space/viewtopic.php?p=246145#p246145 here] (2015)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16828 Proposal for 1.82: support for economic changes] ([[User:Cim|Cim]], 2014)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16735 Cim on introducing the Trade-goods.plist and deprecating the commodities.plist] (2014)
{{QuoteText|Text=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.|Source=([https://bb.oolite.space/viewtopic.php?p=226722#p226722 Cim in Progress Thread (2014)])}}
=== Using the Trade-goods.plist ===
*[https://bb.oolite.space/viewtopic.php?f=4&t=20576 How to get the displayName for a commodity in the Main Station Market?] (2020)
*[https://bb.oolite.space/viewtopic.php?f=6&t=17269 Thinking about Planet Income classification] (2015)

{{QuoteText|Text=
In 1.81 this is a lot easier to OXP - you can introduce as many economies as you like, though you are limited to eight economy symbols (so if you wanted lots of economy types, you might end up with Poor Industrial, Avg Industrial and Rich Industrial sharing a symbol on the map). The trade good pricing scripts can then be used to set up different price categories in different economies (and introduce additional trade goods, or split an existing good into multiple categories, which may be necessary if you're adding more economies).

Resetting economies across the planets is a big change in terms of lines of code, but is also very easy to automate. If OXPers are looking for a scripting tool to use for this sort of automation, then NodeJS or io.js is free and also uses Javascript as its language, so you don't need to learn a new one - and may even be able to share code between your build scripts and your OXP, though I haven't tried that yet.|Source=([https://bb.oolite.space/viewtopic.php?f=6&t=17269 Cim in Planet Income thread (2015)])}}

== Preamble ==
To tweak the pricing/availability of commodities in (''eg''.) a station, you need to define the market inside the station's Shipdata.plist - or include a "hook" inside that shipdata.plist to a javascript Oolite Market Script (which allows more complex definitions).

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:

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

== Handlers ==

=== updateGeneralCommodityDefinition ===
{{oolite-method-added|1.81}}
function updateGeneralCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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 = <code>false</code> 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 ===
{{oolite-method-added|1.81}}
function updateLocalCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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.

[https://bb.oolite.space/viewtopic.php?f=4&t=17621#p239979 Here is an example] of how to use this method.

== Links ==

=== Examples ===
*Phkb's update of [[SW_Economy]] (v.3.10) creates new economies for "mining worlds" (hewn out from some low tech poor agricultural worlds) with utterly different price scales for mineral, agricultural & industrial goods, as well as medicine.

''These others will be found at the bottom of the wiki page on the'' [[Trade-goods.plist]].
*Setting an orbital main station's slaves on sale to zero
*Creating an invariant market independent of the local system economy (agricultural/industrial)

Trade-goods (abridged)

2026-06-18T16:17:17Z

Wildeblood: /* Links */

[[File:SOTL Altmap F8.png|thumb|right|300px|The ''first'' page of commodities from [[SOTL Altmap]], Cim's 2014 experimental scenario]]
'''You are probably looking for [[Trade-goods.plist]]''', rather than this page.

== Preamble ==

The trade-goods.plist file defines "trade goods" (commodities/cargo). But, it does not ''e.g.'' remove slaves from a particular station or make them cost twice as much as they do at the main orbital station. To do such things, ''i.e.'' to tweak the pricing/availability of commodities in a particular station, you need to define the market inside that station, either within its [[Shipdata.plist]] or within a [[Oolite_Market_Scripts|market script]] linked from its shipdata.plist.

== Overview ==

The '''trade-goods.plist''' file is a dictionary of dictionaries, with (canonical) commodity names as keys to dictionaries of key-value pairs 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 [[Oolite_JavaScript_Reference:_Manifest#setComment|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 [[Oolite Market Scripts|market script]] for this trade good when calculating main station quantities and prices.

'''Note:''' [https://bb.oolite.space/viewtopic.php?p=235837#p235837 What's the difference between the market script specified in planetinfo.plist and the one called for by trade-goods.plist?] (2015)

=== name ===
A string containing the name of the trade good. This may contain [keys]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 [[Oolite_JavaScript_Reference:_Manifest#setShortComment|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 ==

The Primary market is that of the main orbital station of the system. The Secondary markets are other station/dockable markets (which are influenced by the primary market), ''eg'' that of a local Rock Hermit, or a visiting liner or another orbital station. Both quantities and prices will be influenced by those of the primary market. Needless to say, the primary market is randomly recalculated each time the system is visited.

Secondary market definitions are entered in the [[shipdata.plist#market_definition|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:

# The market definition array is searched from top to bottom for the first element matching the trade good
# The market quantity is scaled in proportion to the relative capacities for that good in the two markets.
# 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|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 [[shipdata.plist#market_capacity|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 [[shipdata.plist#market_monitored|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.

=== Links ===
*[https://bb.oolite.space/viewtopic.php?f=2&t=21512 Secondary Market Definitions Defined] (2023)

== 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 for determining markets for new stations.

=== From the vanilla game: Rock Hermits ===
The "market_definition" 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: the Trade-goods.plist updated from the original 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;
};

}
=== A new commodity (from the trade-goods.plist inside "SW Economy") ===
"medicine" = {
"name" = "[commodity-name medicine]";
"classes" = ("oolite-consumer","oolite-medical");
"quantity_unit" = 1;
"peak_export" = 7;
"peak_import" = 0;
"price_average" = 640;
"price_economic" = 0.25;
"price_random" = 0.15;
"quantity_average" = 5;
"quantity_economic" = 1.5;
"quantity_random" = 1.0;
"legality_export" = 0;
"legality_import" = 0;
"trumble_opinion" = 0.50;
"sort_order" = 500;
"comment" = "[oolite-commodity-medicine]";
};

=== Setting an orbital main station's slaves on sale to zero ===
[[User:Phkb|Phkb]] provided this example which requires a ''planetinfo.plist'' & a new ''.js file'' - there are other ways to achieve the same result
==== 1) planetinfo.plist (to invoke the market script) ====
(in the "Config" folder)

{
"0 96" = {market_script = "digebiti_noslaves.js";};
}

==== 2) Market script: digebiti_noslaves.js ====
(in the "Scripts" folder) - note the complex name, which prevents confusion with other snippets of script

"use strict";
this.name = "digebiti_noslaves";
this.author = "Phkb";
this.copyright = "(C) 2022 Phkb";
this.licence = "CC-NC-by-SA 4.0";
this.description = "Removes slaves for sale in Digebiti";
this.version = "1.0";

this.updateLocalCommodityDefinition = function(goodDefinition, station, systemID) {
if (goodDefinition.key == "slaves" && station && station.isMainStation) {
goodDefinition.quantity = 0;
}
return goodDefinition;
}

This method will work, so long as no other OXP changes the market_script property of the Digebiti system in the same way.

=== Creating an invariant market independent of the local system economy (agricultural/industrial) ===
If you just use a market_definition in shipdata.plist for the station, then you're merely setting variations on the primary system market.

If you want the station prices to be independent of (or more loosely tied to) the system it's in, then you need to use a [[Oolite_Market_Scripts|market script]].

So what you'd have is something like this - let's say it's a hydroponics station, so it always sells food and nothing else, regardless of whether the general system economy is industrial or agricultural:

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.key == "food") {
// are we calculating the basic Oolite "food" trade good right now? If yes, set our own static prices
goodDefinition.price = 25; // 2.5 credits
goodDefinition.quantity = 80; // lots of food
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

Now ... the reason that market definitions are preferred to be mutators of the system economy is for two reasons.
1) it means you can avoid the situation where you end up with two adjacent stations with wildly different prices ... but you can of course handle that in other ways too, station positioning, restricted access, ''etc''.
2) it makes it easier to handle OXP trade goods:
- other OXPs might have added more "food" type goods, ''e.g.'' "Meat" or "Cheese"
- you can learn about those and handle them specifically

} else if (goodDefinition.key == "bobsfoodoxp_cheese") {
// set price and quantity here

... but that means a lot of keeping up with what everyone else is doing with custom goods.

The idea was that for your hydroponics station what you might do instead is something like this

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So now if another OXP adds Cheese, provided they declare it as "edible", your station will sell it in high quantities at a big discount, but you don't need to know exactly what the baseline price or quantity was set - so if a food-focused OXP was to add "Wine", "Fine Wine" and "Vintage Wine" at a range of prices and quantities, you'd be automatically handling those in reasonable line with a combination of the Wine OXP's basic pricing structure and your station OXP's "food primary source market" style, without necessarily needing to know about every future Wine OXP there might be and explicitly set compatibility.

Note in this example we're still zeroing out all non-food goods - OXP included! - regardless of the local economy. Maybe at this point we'd want to include and document a "hydroponicsoxp-agriculturalequipment" trade good class that other OXPs could use, which this station would buy up at higher demand and prices than normal.

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else if (goodDefinition.classes.indexOf("hydroponicsoxp-agriculturalequipment") >= 0) {
// custom class for other OXPs to add specific agricultural equipment e.g. combine harvesters, compost, fertiliser
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.capacity = 16; // buy a small amount only // TODO: raise capacity if price per tonne is low
goodDefinition.quantity = 0; // not selling this
} else if (goodDefinition.key == "machinery") {
// the basic Oolite Machinery commodity isn't in the custom class but we need to buy something if
// no OXPs adding it are installed
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.quantity = 0; // not selling
goodDefinition.capacity = 16; // small capacity to buy
} else {
// don't buy or sell any other commodity
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So you can see this one has a mix of using, mutating and overruling the definitions set by the system market and OXP commodity definitions ... with this method you could have a whole bunch of OXPs setting up themed stations, and a whole different bunch adding their own custom commodities, and they'd barely have to know about each other to ensure reasonable consistency and compatibility from someone installing any combination of them. (- by [[User:Cim|Cim]], 2023)

Note: this gives examples for 1 commodity at a time, but not how to easily do that for ALL the commodities on ALL the extra stations in a system.

== Using the new Trade-goods.plist ==
The trade-goods.plist was designed to make commodities simpler, by:
:1) Making it a dictionary rather than an unlabelled array so one could tell which parameter was which
:2) Making the price range for a trade good dependent on more sensible variables, so rather than setting the price range with a bitmask, one set the price and quantity variations dependent on the economy and on random chance.

Compare the v.1.81 trade-goods.plist with a v.1.80 commodities.plist - they were designed to give near-identical market behaviour for the built-in trade goods.

But - that only made it more comprehensible. It didn't really let one do anything particularly different to Elite 84 markets - mostly including the "Rich Industrial -> Poor Agricultural" single spectrum. One can tweak that a bit with peak_export and peak_import to get slightly different shapes (so a good might peak at Poor Industrial rather than Rich Industrial) but it doesn't really give one the option of a third economy type still.

''So how does one introduce a new economic pole, such as a mining industry?''

For that, one needs the scripting support. [[Oolite JavaScript Reference: Market Scripts]]. 
One can quite literally do whatever one likes with the prices that way. One could have every *system* have its own separate economy, which varied over time according to events, what the player had previously traded, ''etc. etc.'' to produce something comparable to Elite Dangerous' economic sim, if that's the route one wanted to go down. Obviously the more complexity one adds the harder it gets to script up, but it's now all possible.

[[File:SOTL Altmap F8.png|thumb|right|200px|SOTL Altmap F8 commodities market]]
[[SOTL Altmap]] does have an example of it, which basically throws out the original Elite-like algorithm of trade-goods.plist and starts over. It goes *way* beyond just adding a third economy, too.

Basically in SOTL every trade good is tagged in the trade-goods.plist with a bunch of classes
''e.g.''
classes = ("sotl-ex-salvage","sotl-im-refining","sotl-quantity-high","sotl-priceband-3","sotl-demand-medium","sotl-supply-medium","sotl-volatility-low");
So that means:
- exported by salvage economies
- imported by refining economies
- high quantity, moderate price, low price volatility

Then the market script uses those classes, rather than the standard pricing variables, to define the economic behaviour.
:So line 69-74ish: get the current economy description, convert that to the format used in the class name
:...line 85-90: check for the import and export classes for that economy and see if it's imported or exported
:...lines 100-120: apply various special conditions, so e.g. the sotl-ims-radiation class checks the planet surface radiation levels (custom property in sysinfo) and if the radiation level is high, imports these goods even if the basic economy isn't interested (e.g. "sotl-ceramics-ind" in the plist)
:...and then it uses those calculations (and a bunch more of the classes) in the rest of the script to set the price and quantity depending on whether it's an import, an export, or neither

That's massive overkill for just adding a third mining economy, but one would need to work on a similar principle.

:1) Tag every commodity with classes for (import|export|none)-(agricultural|industrial|mining) as appropriate
:2) Adjust the economy names (there are a few different ways one could do that) so that the 8 economy IDs were allocated to agricultural, industrial and mining economies
:3) Have a price script which like the SOTL one gets the current economy, looks at the classes list to find out if the commodity is imported or exported or neither, and sets the price and quantity accordingly. One could use the standard price_economic, price_average, price_random properties in the plist to give baseline data to the script if one was not planning to do anything too weird.

{Technically one doesn't need the classes - just have the price script contain a list of goods internally for each economy - but this way if other people add extra trade goods in their own OXPs, they can tag them up for mining economy support too}

All fairly straightforward theoretically.

''The biggest impediment to doing a wholesale reworking of the economic system, is just how incompatible it makes lots and lots of OXP's. In order to override the vanilla commodities as in SOTL, requires setting a script for each in trade-goods.plist. Which is fine if it's the only OXP that wants to play around with commodity prices. As soon as two OXP's try to do the same thing, one gets a conflict and no longer knows which OXP pricing model is in play.''

''For SOTL it's fine, because it uses the scenario system to forcibly eject all other OXP's from use while it's running. But if one wants the OXP to go in the general playing pool set of OXP's, it becomes much more complicated. [[User:Phkb|Phkb]] spent a long time trying to work out why his market script wasn't running, only to find that [[UPS Courier]] was quietly adjusting the markets in certain systems via the planetinfo.plist file. And there are a lot of OXP's that want to play in this space, tweaking prices up or down.''

''Hence one usually abandons using any of the script options, and just tweaks the price after all the scripts have finished playing, ''eg'' in [[Smugglers]]. It was the only way to guarantee getting some sort of bump in a price when wanted.''

== Links ==
*[[Oolite JavaScript Reference: Market Scripts]]
*[[Commodities.plist]] - the precursor (which still mostly works!). If it doesn't see [https://bb.oolite.space/viewtopic.php?p=246145#p246145 here] (2015)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16828 Proposal for 1.82: support for economic changes] ([[User:Cim|Cim]], 2014)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16735 Cim on introducing the Trade-goods.plist and deprecating the commodities.plist] (2014)
{{QuoteText|Text=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.|Source=([https://bb.oolite.space/viewtopic.php?p=226722#p226722 Cim in Progress Thread (2014)])}}
=== Using the Trade-goods.plist ===
*[https://bb.oolite.space/viewtopic.php?f=4&t=20576 How to get the displayName for a commodity in the Main Station Market?] (2020)
*[https://bb.oolite.space/viewtopic.php?f=6&t=17269 Thinking about Planet Income classification] (2015)

{{QuoteText|Text=
In 1.81 this is a lot easier to OXP - you can introduce as many economies as you like, though you are limited to eight economy symbols (so if you wanted lots of economy types, you might end up with Poor Industrial, Avg Industrial and Rich Industrial sharing a symbol on the map). The trade good pricing scripts can then be used to set up different price categories in different economies (and introduce additional trade goods, or split an existing good into multiple categories, which may be necessary if you're adding more economies).

Resetting economies across the planets is a big change in terms of lines of code, but is also very easy to automate. If OXPers are looking for a scripting tool to use for this sort of automation, then NodeJS or io.js is free and also uses Javascript as its language, so you don't need to learn a new one - and may even be able to share code between your build scripts and your OXP, though I haven't tried that yet.|Source=([https://bb.oolite.space/viewtopic.php?f=6&t=17269 Cim in Planet Income thread (2015)])}}

== Preamble ==
To tweak the pricing/availability of commodities in (''eg''.) a station, you need to define the market inside the station's Shipdata.plist - or include a "hook" inside that shipdata.plist to a javascript Oolite Market Script (which allows more complex definitions).

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:

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

== Handlers ==

=== updateGeneralCommodityDefinition ===
{{oolite-method-added|1.81}}
function updateGeneralCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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 = <code>false</code> 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 ===
{{oolite-method-added|1.81}}
function updateLocalCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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.

[https://bb.oolite.space/viewtopic.php?f=4&t=17621#p239979 Here is an example] of how to use this method.

== Links ==

=== Examples ===
*Phkb's update of [[SW_Economy]] (v.3.10) creates new economies for "mining worlds" (hewn out from some low tech poor agricultural worlds) with utterly different price scales for mineral, agricultural & industrial goods, as well as medicine.

''These others will be found at the bottom of the wiki page on the'' [[Trade-goods.plist]].
*Setting an orbital main station's slaves on sale to zero
*Creating an invariant market independent of the local system economy (agricultural/industrial)

Trade-goods (abridged)

2026-06-18T15:57:35Z

Wildeblood: /* A new commodity (from the Trade-goods.plist inside "SW Economy") */

[[File:SOTL Altmap F8.png|thumb|right|300px|The ''first'' page of commodities from [[SOTL Altmap]], Cim's 2014 experimental scenario]]
'''You are probably looking for [[Trade-goods.plist]]''', rather than this page.

== Preamble ==

The trade-goods.plist file defines "trade goods" (commodities/cargo). But, it does not ''e.g.'' remove slaves from a particular station or make them cost twice as much as they do at the main orbital station. To do such things, ''i.e.'' to tweak the pricing/availability of commodities in a particular station, you need to define the market inside that station, either within its [[Shipdata.plist]] or within a [[Oolite_Market_Scripts|market script]] linked from its shipdata.plist.

== Overview ==

The '''trade-goods.plist''' file is a dictionary of dictionaries, with (canonical) commodity names as keys to dictionaries of key-value pairs 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 [[Oolite_JavaScript_Reference:_Manifest#setComment|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 [[Oolite Market Scripts|market script]] for this trade good when calculating main station quantities and prices.

'''Note:''' [https://bb.oolite.space/viewtopic.php?p=235837#p235837 What's the difference between the market script specified in planetinfo.plist and the one called for by trade-goods.plist?] (2015)

=== name ===
A string containing the name of the trade good. This may contain [keys]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 [[Oolite_JavaScript_Reference:_Manifest#setShortComment|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 ==

The Primary market is that of the main orbital station of the system. The Secondary markets are other station/dockable markets (which are influenced by the primary market), ''eg'' that of a local Rock Hermit, or a visiting liner or another orbital station. Both quantities and prices will be influenced by those of the primary market. Needless to say, the primary market is randomly recalculated each time the system is visited.

Secondary market definitions are entered in the [[shipdata.plist#market_definition|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:

# The market definition array is searched from top to bottom for the first element matching the trade good
# The market quantity is scaled in proportion to the relative capacities for that good in the two markets.
# 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|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 [[shipdata.plist#market_capacity|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 [[shipdata.plist#market_monitored|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.

=== Links ===
*[https://bb.oolite.space/viewtopic.php?f=2&t=21512 Secondary Market Definitions Defined] (2023)

== 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 for determining markets for new stations.

=== From the vanilla game: Rock Hermits ===
The "market_definition" 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: the Trade-goods.plist updated from the original 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;
};

}
=== A new commodity (from the trade-goods.plist inside "SW Economy") ===
"medicine" = {
"name" = "[commodity-name medicine]";
"classes" = ("oolite-consumer","oolite-medical");
"quantity_unit" = 1;
"peak_export" = 7;
"peak_import" = 0;
"price_average" = 640;
"price_economic" = 0.25;
"price_random" = 0.15;
"quantity_average" = 5;
"quantity_economic" = 1.5;
"quantity_random" = 1.0;
"legality_export" = 0;
"legality_import" = 0;
"trumble_opinion" = 0.50;
"sort_order" = 500;
"comment" = "[oolite-commodity-medicine]";
};

=== Setting an orbital main station's slaves on sale to zero ===
[[User:Phkb|Phkb]] provided this example which requires a ''planetinfo.plist'' & a new ''.js file'' - there are other ways to achieve the same result
==== 1) planetinfo.plist (to invoke the market script) ====
(in the "Config" folder)

{
"0 96" = {market_script = "digebiti_noslaves.js";};
}

==== 2) Market script: digebiti_noslaves.js ====
(in the "Scripts" folder) - note the complex name, which prevents confusion with other snippets of script

"use strict";
this.name = "digebiti_noslaves";
this.author = "Phkb";
this.copyright = "(C) 2022 Phkb";
this.licence = "CC-NC-by-SA 4.0";
this.description = "Removes slaves for sale in Digebiti";
this.version = "1.0";

this.updateLocalCommodityDefinition = function(goodDefinition, station, systemID) {
if (goodDefinition.key == "slaves" && station && station.isMainStation) {
goodDefinition.quantity = 0;
}
return goodDefinition;
}

This method will work, so long as no other OXP changes the market_script property of the Digebiti system in the same way.

=== Creating an invariant market independent of the local system economy (agricultural/industrial) ===
If you just use a market_definition in shipdata.plist for the station, then you're merely setting variations on the primary system market.

If you want the station prices to be independent of (or more loosely tied to) the system it's in, then you need to use a [[Oolite_Market_Scripts|market script]].

So what you'd have is something like this - let's say it's a hydroponics station, so it always sells food and nothing else, regardless of whether the general system economy is industrial or agricultural:

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.key == "food") {
// are we calculating the basic Oolite "food" trade good right now? If yes, set our own static prices
goodDefinition.price = 25; // 2.5 credits
goodDefinition.quantity = 80; // lots of food
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

Now ... the reason that market definitions are preferred to be mutators of the system economy is for two reasons.
1) it means you can avoid the situation where you end up with two adjacent stations with wildly different prices ... but you can of course handle that in other ways too, station positioning, restricted access, ''etc''.
2) it makes it easier to handle OXP trade goods:
- other OXPs might have added more "food" type goods, ''e.g.'' "Meat" or "Cheese"
- you can learn about those and handle them specifically

} else if (goodDefinition.key == "bobsfoodoxp_cheese") {
// set price and quantity here

... but that means a lot of keeping up with what everyone else is doing with custom goods.

The idea was that for your hydroponics station what you might do instead is something like this

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So now if another OXP adds Cheese, provided they declare it as "edible", your station will sell it in high quantities at a big discount, but you don't need to know exactly what the baseline price or quantity was set - so if a food-focused OXP was to add "Wine", "Fine Wine" and "Vintage Wine" at a range of prices and quantities, you'd be automatically handling those in reasonable line with a combination of the Wine OXP's basic pricing structure and your station OXP's "food primary source market" style, without necessarily needing to know about every future Wine OXP there might be and explicitly set compatibility.

Note in this example we're still zeroing out all non-food goods - OXP included! - regardless of the local economy. Maybe at this point we'd want to include and document a "hydroponicsoxp-agriculturalequipment" trade good class that other OXPs could use, which this station would buy up at higher demand and prices than normal.

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else if (goodDefinition.classes.indexOf("hydroponicsoxp-agriculturalequipment") >= 0) {
// custom class for other OXPs to add specific agricultural equipment e.g. combine harvesters, compost, fertiliser
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.capacity = 16; // buy a small amount only // TODO: raise capacity if price per tonne is low
goodDefinition.quantity = 0; // not selling this
} else if (goodDefinition.key == "machinery") {
// the basic Oolite Machinery commodity isn't in the custom class but we need to buy something if
// no OXPs adding it are installed
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.quantity = 0; // not selling
goodDefinition.capacity = 16; // small capacity to buy
} else {
// don't buy or sell any other commodity
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So you can see this one has a mix of using, mutating and overruling the definitions set by the system market and OXP commodity definitions ... with this method you could have a whole bunch of OXPs setting up themed stations, and a whole different bunch adding their own custom commodities, and they'd barely have to know about each other to ensure reasonable consistency and compatibility from someone installing any combination of them. (- by [[User:Cim|Cim]], 2023)

Note: this gives examples for 1 commodity at a time, but not how to easily do that for ALL the commodities on ALL the extra stations in a system.

== Using the new Trade-goods.plist ==
The trade-goods.plist was designed to make commodities simpler, by:
:1) Making it a dictionary rather than an unlabelled array so one could tell which parameter was which
:2) Making the price range for a trade good dependent on more sensible variables, so rather than setting the price range with a bitmask, one set the price and quantity variations dependent on the economy and on random chance.

Compare the v.1.81 trade-goods.plist with a v.1.80 commodities.plist - they were designed to give near-identical market behaviour for the built-in trade goods.

But - that only made it more comprehensible. It didn't really let one do anything particularly different to Elite 84 markets - mostly including the "Rich Industrial -> Poor Agricultural" single spectrum. One can tweak that a bit with peak_export and peak_import to get slightly different shapes (so a good might peak at Poor Industrial rather than Rich Industrial) but it doesn't really give one the option of a third economy type still.

''So how does one introduce a new economic pole, such as a mining industry?''

For that, one needs the scripting support. [[Oolite JavaScript Reference: Market Scripts]]. 
One can quite literally do whatever one likes with the prices that way. One could have every *system* have its own separate economy, which varied over time according to events, what the player had previously traded, ''etc. etc.'' to produce something comparable to Elite Dangerous' economic sim, if that's the route one wanted to go down. Obviously the more complexity one adds the harder it gets to script up, but it's now all possible.

[[File:SOTL Altmap F8.png|thumb|right|200px|SOTL Altmap F8 commodities market]]
[[SOTL Altmap]] does have an example of it, which basically throws out the original Elite-like algorithm of trade-goods.plist and starts over. It goes *way* beyond just adding a third economy, too.

Basically in SOTL every trade good is tagged in the trade-goods.plist with a bunch of classes
''e.g.''
classes = ("sotl-ex-salvage","sotl-im-refining","sotl-quantity-high","sotl-priceband-3","sotl-demand-medium","sotl-supply-medium","sotl-volatility-low");
So that means:
- exported by salvage economies
- imported by refining economies
- high quantity, moderate price, low price volatility

Then the market script uses those classes, rather than the standard pricing variables, to define the economic behaviour.
:So line 69-74ish: get the current economy description, convert that to the format used in the class name
:...line 85-90: check for the import and export classes for that economy and see if it's imported or exported
:...lines 100-120: apply various special conditions, so e.g. the sotl-ims-radiation class checks the planet surface radiation levels (custom property in sysinfo) and if the radiation level is high, imports these goods even if the basic economy isn't interested (e.g. "sotl-ceramics-ind" in the plist)
:...and then it uses those calculations (and a bunch more of the classes) in the rest of the script to set the price and quantity depending on whether it's an import, an export, or neither

That's massive overkill for just adding a third mining economy, but one would need to work on a similar principle.

:1) Tag every commodity with classes for (import|export|none)-(agricultural|industrial|mining) as appropriate
:2) Adjust the economy names (there are a few different ways one could do that) so that the 8 economy IDs were allocated to agricultural, industrial and mining economies
:3) Have a price script which like the SOTL one gets the current economy, looks at the classes list to find out if the commodity is imported or exported or neither, and sets the price and quantity accordingly. One could use the standard price_economic, price_average, price_random properties in the plist to give baseline data to the script if one was not planning to do anything too weird.

{Technically one doesn't need the classes - just have the price script contain a list of goods internally for each economy - but this way if other people add extra trade goods in their own OXPs, they can tag them up for mining economy support too}

All fairly straightforward theoretically.

''The biggest impediment to doing a wholesale reworking of the economic system, is just how incompatible it makes lots and lots of OXP's. In order to override the vanilla commodities as in SOTL, requires setting a script for each in trade-goods.plist. Which is fine if it's the only OXP that wants to play around with commodity prices. As soon as two OXP's try to do the same thing, one gets a conflict and no longer knows which OXP pricing model is in play.''

''For SOTL it's fine, because it uses the scenario system to forcibly eject all other OXP's from use while it's running. But if one wants the OXP to go in the general playing pool set of OXP's, it becomes much more complicated. [[User:Phkb|Phkb]] spent a long time trying to work out why his market script wasn't running, only to find that [[UPS Courier]] was quietly adjusting the markets in certain systems via the planetinfo.plist file. And there are a lot of OXP's that want to play in this space, tweaking prices up or down.''

''Hence one usually abandons using any of the script options, and just tweaks the price after all the scripts have finished playing, ''eg'' in [[Smugglers]]. It was the only way to guarantee getting some sort of bump in a price when wanted.''

== Links ==
*[[Oolite JavaScript Reference: Market Scripts]]
*[[Commodities.plist]] - the precursor (which still mostly works!). If it doesn't see [https://bb.oolite.space/viewtopic.php?p=246145#p246145 here] (2015)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16828 Proposal for 1.82: support for economic changes] ([[User:Cim|Cim]], 2014)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16735 Cim on introducing the Trade-goods.plist and deprecating the commodities.plist] (2014)
{{QuoteText|Text=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.|Source=([https://bb.oolite.space/viewtopic.php?p=226722#p226722 Cim in Progress Thread (2014)])}}
=== Using the Trade-goods.plist ===
*[https://bb.oolite.space/viewtopic.php?f=4&t=20576 How to get the displayName for a commodity in the Main Station Market?] (2020)
*[https://bb.oolite.space/viewtopic.php?f=6&t=17269 Thinking about Planet Income classification] (2015)

{{QuoteText|Text=
In 1.81 this is a lot easier to OXP - you can introduce as many economies as you like, though you are limited to eight economy symbols (so if you wanted lots of economy types, you might end up with Poor Industrial, Avg Industrial and Rich Industrial sharing a symbol on the map). The trade good pricing scripts can then be used to set up different price categories in different economies (and introduce additional trade goods, or split an existing good into multiple categories, which may be necessary if you're adding more economies).

Resetting economies across the planets is a big change in terms of lines of code, but is also very easy to automate. If OXPers are looking for a scripting tool to use for this sort of automation, then NodeJS or io.js is free and also uses Javascript as its language, so you don't need to learn a new one - and may even be able to share code between your build scripts and your OXP, though I haven't tried that yet.|Source=([https://bb.oolite.space/viewtopic.php?f=6&t=17269 Cim in Planet Income thread (2015)])}}

== Preamble ==
To tweak the pricing/availability of commodities in (''eg''.) a station, you need to define the market inside the station's Shipdata.plist - or include a "hook" inside that shipdata.plist to a javascript Oolite Market Script (which allows more complex definitions).

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:

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

== Handlers ==

=== updateGeneralCommodityDefinition ===
{{oolite-method-added|1.81}}
function updateGeneralCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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 = <code>false</code> 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 ===
{{oolite-method-added|1.81}}
function updateLocalCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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.

[https://bb.oolite.space/viewtopic.php?f=4&t=17621#p239979 Here is an example] of how to use this method.

== Links ==
*[[Trade-goods.plist]] which combined the following two .plists:
:*Legacy script: [[Commodities.plist]]
:*Legacy script: [[Misc_plists#illegal_goods.plist|illegal goods.plist]]

=== Examples ===
*Phkb's update of [[SW_Economy]] (v.3.10) creates new economies for "mining worlds" (hewn out from some low tech poor agricultural worlds) with utterly different price scales for mineral, agricultural & industrial goods, as well as medicine.

''These others will be found at the bottom of the wiki page on the'' [[Trade-goods.plist]].
*Setting an orbital main station's slaves on sale to zero
*Creating an invariant market independent of the local system economy (agricultural/industrial)

Trade-goods (abridged)

2026-06-18T15:42:53Z

Wildeblood: /* Overview */ Definition corrected.

'''You are probably looking for [[Trade-goods.plist]]''', rather than this page.

== Preamble ==

The trade-goods.plist file defines "trade goods" (commodities/cargo). But, it does not ''e.g.'' remove slaves from a particular station or make them cost twice as much as they do at the main orbital station. To do such things, ''i.e.'' to tweak the pricing/availability of commodities in a particular station, you need to define the market inside that station, either within its [[Shipdata.plist]] or within a [[Oolite_Market_Scripts|market script]] linked from its shipdata.plist.

== Overview ==

The '''trade-goods.plist''' file is a dictionary of dictionaries, with (canonical) commodity names as keys to dictionaries of key-value pairs 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 [[Oolite_JavaScript_Reference:_Manifest#setComment|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 [[Oolite Market Scripts|market script]] for this trade good when calculating main station quantities and prices.

'''Note:''' [https://bb.oolite.space/viewtopic.php?p=235837#p235837 What's the difference between the market script specified in planetinfo.plist and the one called for by trade-goods.plist?] (2015)

=== name ===
A string containing the name of the trade good. This may contain [keys]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 [[Oolite_JavaScript_Reference:_Manifest#setShortComment|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 ==

The Primary market is that of the main orbital station of the system. The Secondary markets are other station/dockable markets (which are influenced by the primary market), ''eg'' that of a local Rock Hermit, or a visiting liner or another orbital station. Both quantities and prices will be influenced by those of the primary market. Needless to say, the primary market is randomly recalculated each time the system is visited.

Secondary market definitions are entered in the [[shipdata.plist#market_definition|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:

# The market definition array is searched from top to bottom for the first element matching the trade good
# The market quantity is scaled in proportion to the relative capacities for that good in the two markets.
# 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|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 [[shipdata.plist#market_capacity|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 [[shipdata.plist#market_monitored|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.

=== Links ===
*[https://bb.oolite.space/viewtopic.php?f=2&t=21512 Secondary Market Definitions Defined] (2023)

== 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 for determining markets for new stations.

=== From the vanilla game: Rock Hermits ===
The "market_definition" 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: the Trade-goods.plist updated from the original 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;
};

}
=== A new commodity (from the Trade-goods.plist inside "SW Economy") ===
"medicine" = {
"name" = "[commodity-name medicine]";
"classes" = ("oolite-consumer","oolite-medical");
"quantity_unit" = 1;
"peak_export" = 7;
"peak_import" = 0;
"price_average" = 640;
"price_economic" = 0.25;
"price_random" = 0.15;
"quantity_average" = 5;
"quantity_economic" = 1.5;
"quantity_random" = 1.0;
"legality_export" = 0;
"legality_import" = 0;
"trumble_opinion" = 0.50;
"sort_order" = 500;
"comment" = "[oolite-commodity-medicine]";
};

=== Setting an orbital main station's slaves on sale to zero ===
[[User:Phkb|Phkb]] provided this example which requires a ''planetinfo.plist'' & a new ''.js file'' - there are other ways to achieve the same result
==== 1) planetinfo.plist (to invoke the market script) ====
(in the "Config" folder)

{
"0 96" = {market_script = "digebiti_noslaves.js";};
}

==== 2) Market script: digebiti_noslaves.js ====
(in the "Scripts" folder) - note the complex name, which prevents confusion with other snippets of script

"use strict";
this.name = "digebiti_noslaves";
this.author = "Phkb";
this.copyright = "(C) 2022 Phkb";
this.licence = "CC-NC-by-SA 4.0";
this.description = "Removes slaves for sale in Digebiti";
this.version = "1.0";

this.updateLocalCommodityDefinition = function(goodDefinition, station, systemID) {
if (goodDefinition.key == "slaves" && station && station.isMainStation) {
goodDefinition.quantity = 0;
}
return goodDefinition;
}

This method will work, so long as no other OXP changes the market_script property of the Digebiti system in the same way.

=== Creating an invariant market independent of the local system economy (agricultural/industrial) ===
If you just use a market_definition in shipdata.plist for the station, then you're merely setting variations on the primary system market.

If you want the station prices to be independent of (or more loosely tied to) the system it's in, then you need to use a [[Oolite_Market_Scripts|market script]].

So what you'd have is something like this - let's say it's a hydroponics station, so it always sells food and nothing else, regardless of whether the general system economy is industrial or agricultural:

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.key == "food") {
// are we calculating the basic Oolite "food" trade good right now? If yes, set our own static prices
goodDefinition.price = 25; // 2.5 credits
goodDefinition.quantity = 80; // lots of food
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

Now ... the reason that market definitions are preferred to be mutators of the system economy is for two reasons.
1) it means you can avoid the situation where you end up with two adjacent stations with wildly different prices ... but you can of course handle that in other ways too, station positioning, restricted access, ''etc''.
2) it makes it easier to handle OXP trade goods:
- other OXPs might have added more "food" type goods, ''e.g.'' "Meat" or "Cheese"
- you can learn about those and handle them specifically

} else if (goodDefinition.key == "bobsfoodoxp_cheese") {
// set price and quantity here

... but that means a lot of keeping up with what everyone else is doing with custom goods.

The idea was that for your hydroponics station what you might do instead is something like this

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So now if another OXP adds Cheese, provided they declare it as "edible", your station will sell it in high quantities at a big discount, but you don't need to know exactly what the baseline price or quantity was set - so if a food-focused OXP was to add "Wine", "Fine Wine" and "Vintage Wine" at a range of prices and quantities, you'd be automatically handling those in reasonable line with a combination of the Wine OXP's basic pricing structure and your station OXP's "food primary source market" style, without necessarily needing to know about every future Wine OXP there might be and explicitly set compatibility.

Note in this example we're still zeroing out all non-food goods - OXP included! - regardless of the local economy. Maybe at this point we'd want to include and document a "hydroponicsoxp-agriculturalequipment" trade good class that other OXPs could use, which this station would buy up at higher demand and prices than normal.

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else if (goodDefinition.classes.indexOf("hydroponicsoxp-agriculturalequipment") >= 0) {
// custom class for other OXPs to add specific agricultural equipment e.g. combine harvesters, compost, fertiliser
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.capacity = 16; // buy a small amount only // TODO: raise capacity if price per tonne is low
goodDefinition.quantity = 0; // not selling this
} else if (goodDefinition.key == "machinery") {
// the basic Oolite Machinery commodity isn't in the custom class but we need to buy something if
// no OXPs adding it are installed
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.quantity = 0; // not selling
goodDefinition.capacity = 16; // small capacity to buy
} else {
// don't buy or sell any other commodity
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So you can see this one has a mix of using, mutating and overruling the definitions set by the system market and OXP commodity definitions ... with this method you could have a whole bunch of OXPs setting up themed stations, and a whole different bunch adding their own custom commodities, and they'd barely have to know about each other to ensure reasonable consistency and compatibility from someone installing any combination of them. (- by [[User:Cim|Cim]], 2023)

Note: this gives examples for 1 commodity at a time, but not how to easily do that for ALL the commodities on ALL the extra stations in a system.

== Using the new Trade-goods.plist ==
The trade-goods.plist was designed to make commodities simpler, by:
:1) Making it a dictionary rather than an unlabelled array so one could tell which parameter was which
:2) Making the price range for a trade good dependent on more sensible variables, so rather than setting the price range with a bitmask, one set the price and quantity variations dependent on the economy and on random chance.

Compare the v.1.81 trade-goods.plist with a v.1.80 commodities.plist - they were designed to give near-identical market behaviour for the built-in trade goods.

But - that only made it more comprehensible. It didn't really let one do anything particularly different to Elite 84 markets - mostly including the "Rich Industrial -> Poor Agricultural" single spectrum. One can tweak that a bit with peak_export and peak_import to get slightly different shapes (so a good might peak at Poor Industrial rather than Rich Industrial) but it doesn't really give one the option of a third economy type still.

''So how does one introduce a new economic pole, such as a mining industry?''

For that, one needs the scripting support. [[Oolite JavaScript Reference: Market Scripts]]. 
One can quite literally do whatever one likes with the prices that way. One could have every *system* have its own separate economy, which varied over time according to events, what the player had previously traded, ''etc. etc.'' to produce something comparable to Elite Dangerous' economic sim, if that's the route one wanted to go down. Obviously the more complexity one adds the harder it gets to script up, but it's now all possible.

[[File:SOTL Altmap F8.png|thumb|right|200px|SOTL Altmap F8 commodities market]]
[[SOTL Altmap]] does have an example of it, which basically throws out the original Elite-like algorithm of trade-goods.plist and starts over. It goes *way* beyond just adding a third economy, too.

Basically in SOTL every trade good is tagged in the trade-goods.plist with a bunch of classes
''e.g.''
classes = ("sotl-ex-salvage","sotl-im-refining","sotl-quantity-high","sotl-priceband-3","sotl-demand-medium","sotl-supply-medium","sotl-volatility-low");
So that means:
- exported by salvage economies
- imported by refining economies
- high quantity, moderate price, low price volatility

Then the market script uses those classes, rather than the standard pricing variables, to define the economic behaviour.
:So line 69-74ish: get the current economy description, convert that to the format used in the class name
:...line 85-90: check for the import and export classes for that economy and see if it's imported or exported
:...lines 100-120: apply various special conditions, so e.g. the sotl-ims-radiation class checks the planet surface radiation levels (custom property in sysinfo) and if the radiation level is high, imports these goods even if the basic economy isn't interested (e.g. "sotl-ceramics-ind" in the plist)
:...and then it uses those calculations (and a bunch more of the classes) in the rest of the script to set the price and quantity depending on whether it's an import, an export, or neither

That's massive overkill for just adding a third mining economy, but one would need to work on a similar principle.

:1) Tag every commodity with classes for (import|export|none)-(agricultural|industrial|mining) as appropriate
:2) Adjust the economy names (there are a few different ways one could do that) so that the 8 economy IDs were allocated to agricultural, industrial and mining economies
:3) Have a price script which like the SOTL one gets the current economy, looks at the classes list to find out if the commodity is imported or exported or neither, and sets the price and quantity accordingly. One could use the standard price_economic, price_average, price_random properties in the plist to give baseline data to the script if one was not planning to do anything too weird.

{Technically one doesn't need the classes - just have the price script contain a list of goods internally for each economy - but this way if other people add extra trade goods in their own OXPs, they can tag them up for mining economy support too}

All fairly straightforward theoretically.

''The biggest impediment to doing a wholesale reworking of the economic system, is just how incompatible it makes lots and lots of OXP's. In order to override the vanilla commodities as in SOTL, requires setting a script for each in trade-goods.plist. Which is fine if it's the only OXP that wants to play around with commodity prices. As soon as two OXP's try to do the same thing, one gets a conflict and no longer knows which OXP pricing model is in play.''

''For SOTL it's fine, because it uses the scenario system to forcibly eject all other OXP's from use while it's running. But if one wants the OXP to go in the general playing pool set of OXP's, it becomes much more complicated. [[User:Phkb|Phkb]] spent a long time trying to work out why his market script wasn't running, only to find that [[UPS Courier]] was quietly adjusting the markets in certain systems via the planetinfo.plist file. And there are a lot of OXP's that want to play in this space, tweaking prices up or down.''

''Hence one usually abandons using any of the script options, and just tweaks the price after all the scripts have finished playing, ''eg'' in [[Smugglers]]. It was the only way to guarantee getting some sort of bump in a price when wanted.''

== Links ==
*[[Oolite JavaScript Reference: Market Scripts]]
*[[Commodities.plist]] - the precursor (which still mostly works!). If it doesn't see [https://bb.oolite.space/viewtopic.php?p=246145#p246145 here] (2015)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16828 Proposal for 1.82: support for economic changes] ([[User:Cim|Cim]], 2014)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16735 Cim on introducing the Trade-goods.plist and deprecating the commodities.plist] (2014)
{{QuoteText|Text=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.|Source=([https://bb.oolite.space/viewtopic.php?p=226722#p226722 Cim in Progress Thread (2014)])}}
=== Using the Trade-goods.plist ===
*[https://bb.oolite.space/viewtopic.php?f=4&t=20576 How to get the displayName for a commodity in the Main Station Market?] (2020)
*[https://bb.oolite.space/viewtopic.php?f=6&t=17269 Thinking about Planet Income classification] (2015)

{{QuoteText|Text=
In 1.81 this is a lot easier to OXP - you can introduce as many economies as you like, though you are limited to eight economy symbols (so if you wanted lots of economy types, you might end up with Poor Industrial, Avg Industrial and Rich Industrial sharing a symbol on the map). The trade good pricing scripts can then be used to set up different price categories in different economies (and introduce additional trade goods, or split an existing good into multiple categories, which may be necessary if you're adding more economies).

Resetting economies across the planets is a big change in terms of lines of code, but is also very easy to automate. If OXPers are looking for a scripting tool to use for this sort of automation, then NodeJS or io.js is free and also uses Javascript as its language, so you don't need to learn a new one - and may even be able to share code between your build scripts and your OXP, though I haven't tried that yet.|Source=([https://bb.oolite.space/viewtopic.php?f=6&t=17269 Cim in Planet Income thread (2015)])}}

== Preamble ==
To tweak the pricing/availability of commodities in (''eg''.) a station, you need to define the market inside the station's Shipdata.plist - or include a "hook" inside that shipdata.plist to a javascript Oolite Market Script (which allows more complex definitions).

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:

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

== Handlers ==

=== updateGeneralCommodityDefinition ===
{{oolite-method-added|1.81}}
function updateGeneralCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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 = <code>false</code> 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 ===
{{oolite-method-added|1.81}}
function updateLocalCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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.

[https://bb.oolite.space/viewtopic.php?f=4&t=17621#p239979 Here is an example] of how to use this method.

== Links ==
*[[Trade-goods.plist]] which combined the following two .plists:
:*Legacy script: [[Commodities.plist]]
:*Legacy script: [[Misc_plists#illegal_goods.plist|illegal goods.plist]]

=== Examples ===
*Phkb's update of [[SW_Economy]] (v.3.10) creates new economies for "mining worlds" (hewn out from some low tech poor agricultural worlds) with utterly different price scales for mineral, agricultural & industrial goods, as well as medicine.

''These others will be found at the bottom of the wiki page on the'' [[Trade-goods.plist]].
*Setting an orbital main station's slaves on sale to zero
*Creating an invariant market independent of the local system economy (agricultural/industrial)

Trade-goods (abridged)

2026-06-18T11:34:24Z

Wildeblood: /* Using the Trade-goods.plist */

'''You are probably looking for [[Trade-goods.plist]]''', rather than this page.

== Preamble ==

The trade-goods.plist file defines "trade goods" (commodities/cargo). But, it does not ''e.g.'' remove slaves from a particular station or make them cost twice as much as they do at the main orbital station. To do such things, ''i.e.'' to tweak the pricing/availability of commodities in a particular station, you need to define the market inside that station, either within its [[Shipdata.plist]] or within a [[Oolite_Market_Scripts|market script]] linked from its shipdata.plist.

== Overview ==

The Trade-goods.plist 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 [[Oolite_JavaScript_Reference:_Manifest#setComment|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 [[Oolite Market Scripts|market script]] for this trade good when calculating main station quantities and prices.

'''Note:''' [https://bb.oolite.space/viewtopic.php?p=235837#p235837 What's the difference between the market script specified in planetinfo.plist and the one called for by trade-goods.plist?] (2015)

=== name ===
A string containing the name of the trade good. This may contain [keys]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 [[Oolite_JavaScript_Reference:_Manifest#setShortComment|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 ==

The Primary market is that of the main orbital station of the system. The Secondary markets are other station/dockable markets (which are influenced by the primary market), ''eg'' that of a local Rock Hermit, or a visiting liner or another orbital station. Both quantities and prices will be influenced by those of the primary market. Needless to say, the primary market is randomly recalculated each time the system is visited.

Secondary market definitions are entered in the [[shipdata.plist#market_definition|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:

# The market definition array is searched from top to bottom for the first element matching the trade good
# The market quantity is scaled in proportion to the relative capacities for that good in the two markets.
# 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|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 [[shipdata.plist#market_capacity|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 [[shipdata.plist#market_monitored|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.

=== Links ===
*[https://bb.oolite.space/viewtopic.php?f=2&t=21512 Secondary Market Definitions Defined] (2023)

== 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 for determining markets for new stations.

=== From the vanilla game: Rock Hermits ===
The "market_definition" 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: the Trade-goods.plist updated from the original 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;
};

}
=== A new commodity (from the Trade-goods.plist inside "SW Economy") ===
"medicine" = {
"name" = "[commodity-name medicine]";
"classes" = ("oolite-consumer","oolite-medical");
"quantity_unit" = 1;
"peak_export" = 7;
"peak_import" = 0;
"price_average" = 640;
"price_economic" = 0.25;
"price_random" = 0.15;
"quantity_average" = 5;
"quantity_economic" = 1.5;
"quantity_random" = 1.0;
"legality_export" = 0;
"legality_import" = 0;
"trumble_opinion" = 0.50;
"sort_order" = 500;
"comment" = "[oolite-commodity-medicine]";
};

=== Setting an orbital main station's slaves on sale to zero ===
[[User:Phkb|Phkb]] provided this example which requires a ''planetinfo.plist'' & a new ''.js file'' - there are other ways to achieve the same result
==== 1) planetinfo.plist (to invoke the market script) ====
(in the "Config" folder)

{
"0 96" = {market_script = "digebiti_noslaves.js";};
}

==== 2) Market script: digebiti_noslaves.js ====
(in the "Scripts" folder) - note the complex name, which prevents confusion with other snippets of script

"use strict";
this.name = "digebiti_noslaves";
this.author = "Phkb";
this.copyright = "(C) 2022 Phkb";
this.licence = "CC-NC-by-SA 4.0";
this.description = "Removes slaves for sale in Digebiti";
this.version = "1.0";

this.updateLocalCommodityDefinition = function(goodDefinition, station, systemID) {
if (goodDefinition.key == "slaves" && station && station.isMainStation) {
goodDefinition.quantity = 0;
}
return goodDefinition;
}

This method will work, so long as no other OXP changes the market_script property of the Digebiti system in the same way.

=== Creating an invariant market independent of the local system economy (agricultural/industrial) ===
If you just use a market_definition in shipdata.plist for the station, then you're merely setting variations on the primary system market.

If you want the station prices to be independent of (or more loosely tied to) the system it's in, then you need to use a [[Oolite_Market_Scripts|market script]].

So what you'd have is something like this - let's say it's a hydroponics station, so it always sells food and nothing else, regardless of whether the general system economy is industrial or agricultural:

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.key == "food") {
// are we calculating the basic Oolite "food" trade good right now? If yes, set our own static prices
goodDefinition.price = 25; // 2.5 credits
goodDefinition.quantity = 80; // lots of food
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

Now ... the reason that market definitions are preferred to be mutators of the system economy is for two reasons.
1) it means you can avoid the situation where you end up with two adjacent stations with wildly different prices ... but you can of course handle that in other ways too, station positioning, restricted access, ''etc''.
2) it makes it easier to handle OXP trade goods:
- other OXPs might have added more "food" type goods, ''e.g.'' "Meat" or "Cheese"
- you can learn about those and handle them specifically

} else if (goodDefinition.key == "bobsfoodoxp_cheese") {
// set price and quantity here

... but that means a lot of keeping up with what everyone else is doing with custom goods.

The idea was that for your hydroponics station what you might do instead is something like this

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So now if another OXP adds Cheese, provided they declare it as "edible", your station will sell it in high quantities at a big discount, but you don't need to know exactly what the baseline price or quantity was set - so if a food-focused OXP was to add "Wine", "Fine Wine" and "Vintage Wine" at a range of prices and quantities, you'd be automatically handling those in reasonable line with a combination of the Wine OXP's basic pricing structure and your station OXP's "food primary source market" style, without necessarily needing to know about every future Wine OXP there might be and explicitly set compatibility.

Note in this example we're still zeroing out all non-food goods - OXP included! - regardless of the local economy. Maybe at this point we'd want to include and document a "hydroponicsoxp-agriculturalequipment" trade good class that other OXPs could use, which this station would buy up at higher demand and prices than normal.

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else if (goodDefinition.classes.indexOf("hydroponicsoxp-agriculturalequipment") >= 0) {
// custom class for other OXPs to add specific agricultural equipment e.g. combine harvesters, compost, fertiliser
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.capacity = 16; // buy a small amount only // TODO: raise capacity if price per tonne is low
goodDefinition.quantity = 0; // not selling this
} else if (goodDefinition.key == "machinery") {
// the basic Oolite Machinery commodity isn't in the custom class but we need to buy something if
// no OXPs adding it are installed
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.quantity = 0; // not selling
goodDefinition.capacity = 16; // small capacity to buy
} else {
// don't buy or sell any other commodity
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So you can see this one has a mix of using, mutating and overruling the definitions set by the system market and OXP commodity definitions ... with this method you could have a whole bunch of OXPs setting up themed stations, and a whole different bunch adding their own custom commodities, and they'd barely have to know about each other to ensure reasonable consistency and compatibility from someone installing any combination of them. (- by [[User:Cim|Cim]], 2023)

Note: this gives examples for 1 commodity at a time, but not how to easily do that for ALL the commodities on ALL the extra stations in a system.

== Using the new Trade-goods.plist ==
The trade-goods.plist was designed to make commodities simpler, by:
:1) Making it a dictionary rather than an unlabelled array so one could tell which parameter was which
:2) Making the price range for a trade good dependent on more sensible variables, so rather than setting the price range with a bitmask, one set the price and quantity variations dependent on the economy and on random chance.

Compare the v.1.81 trade-goods.plist with a v.1.80 commodities.plist - they were designed to give near-identical market behaviour for the built-in trade goods.

But - that only made it more comprehensible. It didn't really let one do anything particularly different to Elite 84 markets - mostly including the "Rich Industrial -> Poor Agricultural" single spectrum. One can tweak that a bit with peak_export and peak_import to get slightly different shapes (so a good might peak at Poor Industrial rather than Rich Industrial) but it doesn't really give one the option of a third economy type still.

''So how does one introduce a new economic pole, such as a mining industry?''

For that, one needs the scripting support. [[Oolite JavaScript Reference: Market Scripts]]. 
One can quite literally do whatever one likes with the prices that way. One could have every *system* have its own separate economy, which varied over time according to events, what the player had previously traded, ''etc. etc.'' to produce something comparable to Elite Dangerous' economic sim, if that's the route one wanted to go down. Obviously the more complexity one adds the harder it gets to script up, but it's now all possible.

[[File:SOTL Altmap F8.png|thumb|right|200px|SOTL Altmap F8 commodities market]]
[[SOTL Altmap]] does have an example of it, which basically throws out the original Elite-like algorithm of trade-goods.plist and starts over. It goes *way* beyond just adding a third economy, too.

Basically in SOTL every trade good is tagged in the trade-goods.plist with a bunch of classes
''e.g.''
classes = ("sotl-ex-salvage","sotl-im-refining","sotl-quantity-high","sotl-priceband-3","sotl-demand-medium","sotl-supply-medium","sotl-volatility-low");
So that means:
- exported by salvage economies
- imported by refining economies
- high quantity, moderate price, low price volatility

Then the market script uses those classes, rather than the standard pricing variables, to define the economic behaviour.
:So line 69-74ish: get the current economy description, convert that to the format used in the class name
:...line 85-90: check for the import and export classes for that economy and see if it's imported or exported
:...lines 100-120: apply various special conditions, so e.g. the sotl-ims-radiation class checks the planet surface radiation levels (custom property in sysinfo) and if the radiation level is high, imports these goods even if the basic economy isn't interested (e.g. "sotl-ceramics-ind" in the plist)
:...and then it uses those calculations (and a bunch more of the classes) in the rest of the script to set the price and quantity depending on whether it's an import, an export, or neither

That's massive overkill for just adding a third mining economy, but one would need to work on a similar principle.

:1) Tag every commodity with classes for (import|export|none)-(agricultural|industrial|mining) as appropriate
:2) Adjust the economy names (there are a few different ways one could do that) so that the 8 economy IDs were allocated to agricultural, industrial and mining economies
:3) Have a price script which like the SOTL one gets the current economy, looks at the classes list to find out if the commodity is imported or exported or neither, and sets the price and quantity accordingly. One could use the standard price_economic, price_average, price_random properties in the plist to give baseline data to the script if one was not planning to do anything too weird.

{Technically one doesn't need the classes - just have the price script contain a list of goods internally for each economy - but this way if other people add extra trade goods in their own OXPs, they can tag them up for mining economy support too}

All fairly straightforward theoretically.

''The biggest impediment to doing a wholesale reworking of the economic system, is just how incompatible it makes lots and lots of OXP's. In order to override the vanilla commodities as in SOTL, requires setting a script for each in trade-goods.plist. Which is fine if it's the only OXP that wants to play around with commodity prices. As soon as two OXP's try to do the same thing, one gets a conflict and no longer knows which OXP pricing model is in play.''

''For SOTL it's fine, because it uses the scenario system to forcibly eject all other OXP's from use while it's running. But if one wants the OXP to go in the general playing pool set of OXP's, it becomes much more complicated. [[User:Phkb|Phkb]] spent a long time trying to work out why his market script wasn't running, only to find that [[UPS Courier]] was quietly adjusting the markets in certain systems via the planetinfo.plist file. And there are a lot of OXP's that want to play in this space, tweaking prices up or down.''

''Hence one usually abandons using any of the script options, and just tweaks the price after all the scripts have finished playing, ''eg'' in [[Smugglers]]. It was the only way to guarantee getting some sort of bump in a price when wanted.''

== Links ==
*[[Oolite JavaScript Reference: Market Scripts]]
*[[Commodities.plist]] - the precursor (which still mostly works!). If it doesn't see [https://bb.oolite.space/viewtopic.php?p=246145#p246145 here] (2015)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16828 Proposal for 1.82: support for economic changes] ([[User:Cim|Cim]], 2014)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16735 Cim on introducing the Trade-goods.plist and deprecating the commodities.plist] (2014)
{{QuoteText|Text=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.|Source=([https://bb.oolite.space/viewtopic.php?p=226722#p226722 Cim in Progress Thread (2014)])}}
=== Using the Trade-goods.plist ===
*[https://bb.oolite.space/viewtopic.php?f=4&t=20576 How to get the displayName for a commodity in the Main Station Market?] (2020)
*[https://bb.oolite.space/viewtopic.php?f=6&t=17269 Thinking about Planet Income classification] (2015)

{{QuoteText|Text=
In 1.81 this is a lot easier to OXP - you can introduce as many economies as you like, though you are limited to eight economy symbols (so if you wanted lots of economy types, you might end up with Poor Industrial, Avg Industrial and Rich Industrial sharing a symbol on the map). The trade good pricing scripts can then be used to set up different price categories in different economies (and introduce additional trade goods, or split an existing good into multiple categories, which may be necessary if you're adding more economies).

Resetting economies across the planets is a big change in terms of lines of code, but is also very easy to automate. If OXPers are looking for a scripting tool to use for this sort of automation, then NodeJS or io.js is free and also uses Javascript as its language, so you don't need to learn a new one - and may even be able to share code between your build scripts and your OXP, though I haven't tried that yet.|Source=([https://bb.oolite.space/viewtopic.php?f=6&t=17269 Cim in Planet Income thread (2015)])}}

== Preamble ==
To tweak the pricing/availability of commodities in (''eg''.) a station, you need to define the market inside the station's Shipdata.plist - or include a "hook" inside that shipdata.plist to a javascript Oolite Market Script (which allows more complex definitions).

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:

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

== Handlers ==

=== updateGeneralCommodityDefinition ===
{{oolite-method-added|1.81}}
function updateGeneralCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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 = <code>false</code> 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 ===
{{oolite-method-added|1.81}}
function updateLocalCommodityDefinition (goodDefinition : Object, station : [[Oolite_JavaScript_Reference:_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.

[https://bb.oolite.space/viewtopic.php?f=4&t=17621#p239979 Here is an example] of how to use this method.

== Links ==
*[[Trade-goods.plist]] which combined the following two .plists:
:*Legacy script: [[Commodities.plist]]
:*Legacy script: [[Misc_plists#illegal_goods.plist|illegal goods.plist]]

=== Examples ===
*Phkb's update of [[SW_Economy]] (v.3.10) creates new economies for "mining worlds" (hewn out from some low tech poor agricultural worlds) with utterly different price scales for mineral, agricultural & industrial goods, as well as medicine.

''These others will be found at the bottom of the wiki page on the'' [[Trade-goods.plist]].
*Setting an orbital main station's slaves on sale to zero
*Creating an invariant market independent of the local system economy (agricultural/industrial)

Trade-goods (abridged)

2026-06-18T10:26:06Z

Wildeblood: /* Using the new Trade-goods.plist */

'''You are probably looking for [[Trade-goods.plist]]''', rather than this page.

== Preamble ==

The trade-goods.plist file defines "trade goods" (commodities/cargo). But, it does not ''e.g.'' remove slaves from a particular station or make them cost twice as much as they do at the main orbital station. To do such things, ''i.e.'' to tweak the pricing/availability of commodities in a particular station, you need to define the market inside that station, either within its [[Shipdata.plist]] or within a [[Oolite_Market_Scripts|market script]] linked from its shipdata.plist.

== Overview ==

The Trade-goods.plist 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 [[Oolite_JavaScript_Reference:_Manifest#setComment|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 [[Oolite Market Scripts|market script]] for this trade good when calculating main station quantities and prices.

'''Note:''' [https://bb.oolite.space/viewtopic.php?p=235837#p235837 What's the difference between the market script specified in planetinfo.plist and the one called for by trade-goods.plist?] (2015)

=== name ===
A string containing the name of the trade good. This may contain [keys]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 [[Oolite_JavaScript_Reference:_Manifest#setShortComment|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 ==

The Primary market is that of the main orbital station of the system. The Secondary markets are other station/dockable markets (which are influenced by the primary market), ''eg'' that of a local Rock Hermit, or a visiting liner or another orbital station. Both quantities and prices will be influenced by those of the primary market. Needless to say, the primary market is randomly recalculated each time the system is visited.

Secondary market definitions are entered in the [[shipdata.plist#market_definition|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:

# The market definition array is searched from top to bottom for the first element matching the trade good
# The market quantity is scaled in proportion to the relative capacities for that good in the two markets.
# 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|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 [[shipdata.plist#market_capacity|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 [[shipdata.plist#market_monitored|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.

=== Links ===
*[https://bb.oolite.space/viewtopic.php?f=2&t=21512 Secondary Market Definitions Defined] (2023)

== 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 for determining markets for new stations.

=== From the vanilla game: Rock Hermits ===
The "market_definition" 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: the Trade-goods.plist updated from the original 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;
};

}
=== A new commodity (from the Trade-goods.plist inside "SW Economy") ===
"medicine" = {
"name" = "[commodity-name medicine]";
"classes" = ("oolite-consumer","oolite-medical");
"quantity_unit" = 1;
"peak_export" = 7;
"peak_import" = 0;
"price_average" = 640;
"price_economic" = 0.25;
"price_random" = 0.15;
"quantity_average" = 5;
"quantity_economic" = 1.5;
"quantity_random" = 1.0;
"legality_export" = 0;
"legality_import" = 0;
"trumble_opinion" = 0.50;
"sort_order" = 500;
"comment" = "[oolite-commodity-medicine]";
};

=== Setting an orbital main station's slaves on sale to zero ===
[[User:Phkb|Phkb]] provided this example which requires a ''planetinfo.plist'' & a new ''.js file'' - there are other ways to achieve the same result
==== 1) planetinfo.plist (to invoke the market script) ====
(in the "Config" folder)

{
"0 96" = {market_script = "digebiti_noslaves.js";};
}

==== 2) Market script: digebiti_noslaves.js ====
(in the "Scripts" folder) - note the complex name, which prevents confusion with other snippets of script

"use strict";
this.name = "digebiti_noslaves";
this.author = "Phkb";
this.copyright = "(C) 2022 Phkb";
this.licence = "CC-NC-by-SA 4.0";
this.description = "Removes slaves for sale in Digebiti";
this.version = "1.0";

this.updateLocalCommodityDefinition = function(goodDefinition, station, systemID) {
if (goodDefinition.key == "slaves" && station && station.isMainStation) {
goodDefinition.quantity = 0;
}
return goodDefinition;
}

This method will work, so long as no other OXP changes the market_script property of the Digebiti system in the same way.

=== Creating an invariant market independent of the local system economy (agricultural/industrial) ===
If you just use a market_definition in shipdata.plist for the station, then you're merely setting variations on the primary system market.

If you want the station prices to be independent of (or more loosely tied to) the system it's in, then you need to use a [[Oolite_Market_Scripts|market script]].

So what you'd have is something like this - let's say it's a hydroponics station, so it always sells food and nothing else, regardless of whether the general system economy is industrial or agricultural:

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.key == "food") {
// are we calculating the basic Oolite "food" trade good right now? If yes, set our own static prices
goodDefinition.price = 25; // 2.5 credits
goodDefinition.quantity = 80; // lots of food
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

Now ... the reason that market definitions are preferred to be mutators of the system economy is for two reasons.
1) it means you can avoid the situation where you end up with two adjacent stations with wildly different prices ... but you can of course handle that in other ways too, station positioning, restricted access, ''etc''.
2) it makes it easier to handle OXP trade goods:
- other OXPs might have added more "food" type goods, ''e.g.'' "Meat" or "Cheese"
- you can learn about those and handle them specifically

} else if (goodDefinition.key == "bobsfoodoxp_cheese") {
// set price and quantity here

... but that means a lot of keeping up with what everyone else is doing with custom goods.

The idea was that for your hydroponics station what you might do instead is something like this

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So now if another OXP adds Cheese, provided they declare it as "edible", your station will sell it in high quantities at a big discount, but you don't need to know exactly what the baseline price or quantity was set - so if a food-focused OXP was to add "Wine", "Fine Wine" and "Vintage Wine" at a range of prices and quantities, you'd be automatically handling those in reasonable line with a combination of the Wine OXP's basic pricing structure and your station OXP's "food primary source market" style, without necessarily needing to know about every future Wine OXP there might be and explicitly set compatibility.

Note in this example we're still zeroing out all non-food goods - OXP included! - regardless of the local economy. Maybe at this point we'd want to include and document a "hydroponicsoxp-agriculturalequipment" trade good class that other OXPs could use, which this station would buy up at higher demand and prices than normal.

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else if (goodDefinition.classes.indexOf("hydroponicsoxp-agriculturalequipment") >= 0) {
// custom class for other OXPs to add specific agricultural equipment e.g. combine harvesters, compost, fertiliser
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.capacity = 16; // buy a small amount only // TODO: raise capacity if price per tonne is low
goodDefinition.quantity = 0; // not selling this
} else if (goodDefinition.key == "machinery") {
// the basic Oolite Machinery commodity isn't in the custom class but we need to buy something if
// no OXPs adding it are installed
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.quantity = 0; // not selling
goodDefinition.capacity = 16; // small capacity to buy
} else {
// don't buy or sell any other commodity
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So you can see this one has a mix of using, mutating and overruling the definitions set by the system market and OXP commodity definitions ... with this method you could have a whole bunch of OXPs setting up themed stations, and a whole different bunch adding their own custom commodities, and they'd barely have to know about each other to ensure reasonable consistency and compatibility from someone installing any combination of them. (- by [[User:Cim|Cim]], 2023)

Note: this gives examples for 1 commodity at a time, but not how to easily do that for ALL the commodities on ALL the extra stations in a system.

== Using the new Trade-goods.plist ==
The trade-goods.plist was designed to make commodities simpler, by:
:1) Making it a dictionary rather than an unlabelled array so one could tell which parameter was which
:2) Making the price range for a trade good dependent on more sensible variables, so rather than setting the price range with a bitmask, one set the price and quantity variations dependent on the economy and on random chance.

Compare the v.1.81 trade-goods.plist with a v.1.80 commodities.plist - they were designed to give near-identical market behaviour for the built-in trade goods.

But - that only made it more comprehensible. It didn't really let one do anything particularly different to Elite 84 markets - mostly including the "Rich Industrial -> Poor Agricultural" single spectrum. One can tweak that a bit with peak_export and peak_import to get slightly different shapes (so a good might peak at Poor Industrial rather than Rich Industrial) but it doesn't really give one the option of a third economy type still.

''So how does one introduce a new economic pole, such as a mining industry?''

For that, one needs the scripting support. [[Oolite JavaScript Reference: Market Scripts]]. 
One can quite literally do whatever one likes with the prices that way. One could have every *system* have its own separate economy, which varied over time according to events, what the player had previously traded, ''etc. etc.'' to produce something comparable to Elite Dangerous' economic sim, if that's the route one wanted to go down. Obviously the more complexity one adds the harder it gets to script up, but it's now all possible.

[[File:SOTL Altmap F8.png|thumb|right|200px|SOTL Altmap F8 commodities market]]
[[SOTL Altmap]] does have an example of it, which basically throws out the original Elite-like algorithm of trade-goods.plist and starts over. It goes *way* beyond just adding a third economy, too.

Basically in SOTL every trade good is tagged in the trade-goods.plist with a bunch of classes
''e.g.''
classes = ("sotl-ex-salvage","sotl-im-refining","sotl-quantity-high","sotl-priceband-3","sotl-demand-medium","sotl-supply-medium","sotl-volatility-low");
So that means:
- exported by salvage economies
- imported by refining economies
- high quantity, moderate price, low price volatility

Then the market script uses those classes, rather than the standard pricing variables, to define the economic behaviour.
:So line 69-74ish: get the current economy description, convert that to the format used in the class name
:...line 85-90: check for the import and export classes for that economy and see if it's imported or exported
:...lines 100-120: apply various special conditions, so e.g. the sotl-ims-radiation class checks the planet surface radiation levels (custom property in sysinfo) and if the radiation level is high, imports these goods even if the basic economy isn't interested (e.g. "sotl-ceramics-ind" in the plist)
:...and then it uses those calculations (and a bunch more of the classes) in the rest of the script to set the price and quantity depending on whether it's an import, an export, or neither

That's massive overkill for just adding a third mining economy, but one would need to work on a similar principle.

:1) Tag every commodity with classes for (import|export|none)-(agricultural|industrial|mining) as appropriate
:2) Adjust the economy names (there are a few different ways one could do that) so that the 8 economy IDs were allocated to agricultural, industrial and mining economies
:3) Have a price script which like the SOTL one gets the current economy, looks at the classes list to find out if the commodity is imported or exported or neither, and sets the price and quantity accordingly. One could use the standard price_economic, price_average, price_random properties in the plist to give baseline data to the script if one was not planning to do anything too weird.

{Technically one doesn't need the classes - just have the price script contain a list of goods internally for each economy - but this way if other people add extra trade goods in their own OXPs, they can tag them up for mining economy support too}

All fairly straightforward theoretically.

''The biggest impediment to doing a wholesale reworking of the economic system, is just how incompatible it makes lots and lots of OXP's. In order to override the vanilla commodities as in SOTL, requires setting a script for each in trade-goods.plist. Which is fine if it's the only OXP that wants to play around with commodity prices. As soon as two OXP's try to do the same thing, one gets a conflict and no longer knows which OXP pricing model is in play.''

''For SOTL it's fine, because it uses the scenario system to forcibly eject all other OXP's from use while it's running. But if one wants the OXP to go in the general playing pool set of OXP's, it becomes much more complicated. [[User:Phkb|Phkb]] spent a long time trying to work out why his market script wasn't running, only to find that [[UPS Courier]] was quietly adjusting the markets in certain systems via the planetinfo.plist file. And there are a lot of OXP's that want to play in this space, tweaking prices up or down.''

''Hence one usually abandons using any of the script options, and just tweaks the price after all the scripts have finished playing, ''eg'' in [[Smugglers]]. It was the only way to guarantee getting some sort of bump in a price when wanted.''

== Links ==
*[[Oolite JavaScript Reference: Market Scripts]]
*[[Commodities.plist]] - the precursor (which still mostly works!). If it doesn't see [https://bb.oolite.space/viewtopic.php?p=246145#p246145 here] (2015)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16828 Proposal for 1.82: support for economic changes] ([[User:Cim|Cim]], 2014)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16735 Cim on introducing the Trade-goods.plist and deprecating the commodities.plist] (2014)
{{QuoteText|Text=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.|Source=([https://bb.oolite.space/viewtopic.php?p=226722#p226722 Cim in Progress Thread (2014)])}}
=== Using the Trade-goods.plist ===
*[https://bb.oolite.space/viewtopic.php?f=4&t=20576 How to get the displayName for a commodity in the Main Station Market?] (2020)
*[https://bb.oolite.space/viewtopic.php?f=6&t=17269 Thinking about Planet Income classification] (2015)

{{QuoteText|Text=
In 1.81 this is a lot easier to OXP - you can introduce as many economies as you like, though you are limited to eight economy symbols (so if you wanted lots of economy types, you might end up with Poor Industrial, Avg Industrial and Rich Industrial sharing a symbol on the map). The trade good pricing scripts can then be used to set up different price categories in different economies (and introduce additional trade goods, or split an existing good into multiple categories, which may be necessary if you're adding more economies).

Resetting economies across the planets is a big change in terms of lines of code, but is also very easy to automate. If OXPers are looking for a scripting tool to use for this sort of automation, then NodeJS or io.js is free and also uses Javascript as its language, so you don't need to learn a new one - and may even be able to share code between your build scripts and your OXP, though I haven't tried that yet.|Source=([https://bb.oolite.space/viewtopic.php?f=6&t=17269 Cim in Planet Income thread (2015)])}}

[[Category:Oolite]]
[[Category:Oolite scripting]]

Trade-goods (abridged)

2026-06-18T09:44:33Z

Wildeblood: /* Preamble */

'''You are probably looking for [[Trade-goods.plist]]''', rather than this page.

== Preamble ==

The trade-goods.plist file defines "trade goods" (commodities/cargo). But, it does not ''e.g.'' remove slaves from a particular station or make them cost twice as much as they do at the main orbital station. To do such things, ''i.e.'' to tweak the pricing/availability of commodities in a particular station, you need to define the market inside that station, either within its [[Shipdata.plist]] or within a [[Oolite_Market_Scripts|market script]] linked from its shipdata.plist.

== Overview ==

The Trade-goods.plist 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 [[Oolite_JavaScript_Reference:_Manifest#setComment|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 [[Oolite Market Scripts|market script]] for this trade good when calculating main station quantities and prices.

'''Note:''' [https://bb.oolite.space/viewtopic.php?p=235837#p235837 What's the difference between the market script specified in planetinfo.plist and the one called for by trade-goods.plist?] (2015)

=== name ===
A string containing the name of the trade good. This may contain [keys]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 [[Oolite_JavaScript_Reference:_Manifest#setShortComment|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 ==

The Primary market is that of the main orbital station of the system. The Secondary markets are other station/dockable markets (which are influenced by the primary market), ''eg'' that of a local Rock Hermit, or a visiting liner or another orbital station. Both quantities and prices will be influenced by those of the primary market. Needless to say, the primary market is randomly recalculated each time the system is visited.

Secondary market definitions are entered in the [[shipdata.plist#market_definition|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:

# The market definition array is searched from top to bottom for the first element matching the trade good
# The market quantity is scaled in proportion to the relative capacities for that good in the two markets.
# 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|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 [[shipdata.plist#market_capacity|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 [[shipdata.plist#market_monitored|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.

=== Links ===
*[https://bb.oolite.space/viewtopic.php?f=2&t=21512 Secondary Market Definitions Defined] (2023)

== 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 for determining markets for new stations.

=== From the vanilla game: Rock Hermits ===
The "market_definition" 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: the Trade-goods.plist updated from the original 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;
};

}
=== A new commodity (from the Trade-goods.plist inside "SW Economy") ===
"medicine" = {
"name" = "[commodity-name medicine]";
"classes" = ("oolite-consumer","oolite-medical");
"quantity_unit" = 1;
"peak_export" = 7;
"peak_import" = 0;
"price_average" = 640;
"price_economic" = 0.25;
"price_random" = 0.15;
"quantity_average" = 5;
"quantity_economic" = 1.5;
"quantity_random" = 1.0;
"legality_export" = 0;
"legality_import" = 0;
"trumble_opinion" = 0.50;
"sort_order" = 500;
"comment" = "[oolite-commodity-medicine]";
};

=== Setting an orbital main station's slaves on sale to zero ===
[[User:Phkb|Phkb]] provided this example which requires a ''planetinfo.plist'' & a new ''.js file'' - there are other ways to achieve the same result
==== 1) planetinfo.plist (to invoke the market script) ====
(in the "Config" folder)

{
"0 96" = {market_script = "digebiti_noslaves.js";};
}

==== 2) Market script: digebiti_noslaves.js ====
(in the "Scripts" folder) - note the complex name, which prevents confusion with other snippets of script

"use strict";
this.name = "digebiti_noslaves";
this.author = "Phkb";
this.copyright = "(C) 2022 Phkb";
this.licence = "CC-NC-by-SA 4.0";
this.description = "Removes slaves for sale in Digebiti";
this.version = "1.0";

this.updateLocalCommodityDefinition = function(goodDefinition, station, systemID) {
if (goodDefinition.key == "slaves" && station && station.isMainStation) {
goodDefinition.quantity = 0;
}
return goodDefinition;
}

This method will work, so long as no other OXP changes the market_script property of the Digebiti system in the same way.

=== Creating an invariant market independent of the local system economy (agricultural/industrial) ===
If you just use a market_definition in shipdata.plist for the station, then you're merely setting variations on the primary system market.

If you want the station prices to be independent of (or more loosely tied to) the system it's in, then you need to use a [[Oolite_Market_Scripts|market script]].

So what you'd have is something like this - let's say it's a hydroponics station, so it always sells food and nothing else, regardless of whether the general system economy is industrial or agricultural:

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.key == "food") {
// are we calculating the basic Oolite "food" trade good right now? If yes, set our own static prices
goodDefinition.price = 25; // 2.5 credits
goodDefinition.quantity = 80; // lots of food
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

Now ... the reason that market definitions are preferred to be mutators of the system economy is for two reasons.
1) it means you can avoid the situation where you end up with two adjacent stations with wildly different prices ... but you can of course handle that in other ways too, station positioning, restricted access, ''etc''.
2) it makes it easier to handle OXP trade goods:
- other OXPs might have added more "food" type goods, ''e.g.'' "Meat" or "Cheese"
- you can learn about those and handle them specifically

} else if (goodDefinition.key == "bobsfoodoxp_cheese") {
// set price and quantity here

... but that means a lot of keeping up with what everyone else is doing with custom goods.

The idea was that for your hydroponics station what you might do instead is something like this

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So now if another OXP adds Cheese, provided they declare it as "edible", your station will sell it in high quantities at a big discount, but you don't need to know exactly what the baseline price or quantity was set - so if a food-focused OXP was to add "Wine", "Fine Wine" and "Vintage Wine" at a range of prices and quantities, you'd be automatically handling those in reasonable line with a combination of the Wine OXP's basic pricing structure and your station OXP's "food primary source market" style, without necessarily needing to know about every future Wine OXP there might be and explicitly set compatibility.

Note in this example we're still zeroing out all non-food goods - OXP included! - regardless of the local economy. Maybe at this point we'd want to include and document a "hydroponicsoxp-agriculturalequipment" trade good class that other OXPs could use, which this station would buy up at higher demand and prices than normal.

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else if (goodDefinition.classes.indexOf("hydroponicsoxp-agriculturalequipment") >= 0) {
// custom class for other OXPs to add specific agricultural equipment e.g. combine harvesters, compost, fertiliser
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.capacity = 16; // buy a small amount only // TODO: raise capacity if price per tonne is low
goodDefinition.quantity = 0; // not selling this
} else if (goodDefinition.key == "machinery") {
// the basic Oolite Machinery commodity isn't in the custom class but we need to buy something if
// no OXPs adding it are installed
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.quantity = 0; // not selling
goodDefinition.capacity = 16; // small capacity to buy
} else {
// don't buy or sell any other commodity
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So you can see this one has a mix of using, mutating and overruling the definitions set by the system market and OXP commodity definitions ... with this method you could have a whole bunch of OXPs setting up themed stations, and a whole different bunch adding their own custom commodities, and they'd barely have to know about each other to ensure reasonable consistency and compatibility from someone installing any combination of them. (- by [[User:Cim|Cim]], 2023)

Note: this gives examples for 1 commodity at a time, but not how to easily do that for ALL the commodities on ALL the extra stations in a system.

== Using the new Trade-goods.plist ==
The original commodities.plist was really not very good - it was based very strongly on the original Elite 84 pricing algorithm, which was written to use peculiarities of 8-bit Maths to its advantage. So one ended up with a series of fairly incomprehensible integers defining each market.

The trade-goods.plist was designed to make that simpler, by:
:1) Making it a dictionary rather than an unlabelled array so one could tell which parameter was which
:2) Making the price range for a trade good dependent on more sensible variables, so rather than setting the price range with a bitmask, one set the price and quantity variations dependent on the economy and on random chance.

Compare the v.1.81 trade-goods.plist with a v.1.80 commodities.plist - they were designed to give near-identical market behaviour for the built-in trade goods.

But - that only made it more comprehensible. It didn't really let one do anything particularly different to Elite 84 markets - mostly including the "Rich Industrial -> Poor Agricultural" single spectrum. One can tweak that a bit with peak_export and peak_import to get slightly different shapes (so a good might peak at Poor Industrial rather than Rich Industrial) but it doesn't really give one the option of a third economy type still.

''So how does one introduce a new economic pole, such as a mining industry?''

For that, one needs the scripting support. [[Oolite JavaScript Reference: Market Scripts]]. 
One can quite literally do whatever one likes with the prices that way. One could have every *system* have its own separate economy, which varied over time according to events, what the player had previously traded, ''etc. etc.'' to produce something comparable to Elite Dangerous' economic sim, if that's the route one wanted to go down. Obviously the more complexity one adds the harder it gets to script up, but it's now all possible.

[[File:SOTL Altmap F8.png|thumb|right|200px|SOTL Altmap F8 commodities market]]
[[SOTL Altmap]] does have an example of it, which basically throws out the original Elite-like algorithm of trade-goods.plist and starts over. It goes *way* beyond just adding a third economy, too.

Basically in SOTL every trade good is tagged in the trade-goods.plist with a bunch of classes
''e.g.''
classes = ("sotl-ex-salvage","sotl-im-refining","sotl-quantity-high","sotl-priceband-3","sotl-demand-medium","sotl-supply-medium","sotl-volatility-low");
So that means:
- exported by salvage economies
- imported by refining economies
- high quantity, moderate price, low price volatility

Then the market script uses those classes, rather than the standard pricing variables, to define the economic behaviour.
:So line 69-74ish: get the current economy description, convert that to the format used in the class name
:...line 85-90: check for the import and export classes for that economy and see if it's imported or exported
:...lines 100-120: apply various special conditions, so e.g. the sotl-ims-radiation class checks the planet surface radiation levels (custom property in sysinfo) and if the radiation level is high, imports these goods even if the basic economy isn't interested (e.g. "sotl-ceramics-ind" in the plist)
:...and then it uses those calculations (and a bunch more of the classes) in the rest of the script to set the price and quantity depending on whether it's an import, an export, or neither

That's massive overkill for just adding a third mining economy, but one would need to work on a similar principle.

:1) Tag every commodity with classes for (import|export|none)-(agricultural|industrial|mining) as appropriate
:2) Adjust the economy names (there are a few different ways one could do that) so that the 8 economy IDs were allocated to agricultural, industrial and mining economies
:3) Have a price script which like the SOTL one gets the current economy, looks at the classes list to find out if the commodity is imported or exported or neither, and sets the price and quantity accordingly. One could use the standard price_economic, price_average, price_random properties in the plist to give baseline data to the script if one was not planning to do anything too weird.

{Technically one doesn't need the classes - just have the price script contain a list of goods internally for each economy - but this way if other people add extra trade goods in their own OXPs, they can tag them up for mining economy support too}

All fairly straightforward theoretically.

''The biggest impediment to doing a wholesale reworking of the economic system, is just how incompatible it makes lots and lots of OXP's. In order to override the vanilla commodities as in SOTL, requires setting a script for each in trade-goods.plist. Which is fine if it's the only OXP that wants to play around with commodity prices. As soon as two OXP's try to do the same thing, one gets a conflict and no longer knows which OXP pricing model is in play.''

''For SOTL it's fine, because it uses the scenario system to forcibly eject all other OXP's from use while it's running. But if one wants the OXP to go in the general playing pool set of OXP's, it becomes much more complicated. [[User:Phkb|Phkb]] spent a long time trying to work out why his market script wasn't running, only to find that [[UPS Courier]] was quietly adjusting the markets in certain systems via the planetinfo.plist file. And there are a lot of OXP's that want to play in this space, tweaking prices up or down.''

''Hence one usually abandons using any of the script options, and just tweaks the price after all the scripts have finished playing, ''eg'' in [[Smugglers]]. It was the only way to guarantee getting some sort of bump in a price when wanted.''

== Links ==
*[[Oolite JavaScript Reference: Market Scripts]]
*[[Commodities.plist]] - the precursor (which still mostly works!). If it doesn't see [https://bb.oolite.space/viewtopic.php?p=246145#p246145 here] (2015)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16828 Proposal for 1.82: support for economic changes] ([[User:Cim|Cim]], 2014)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16735 Cim on introducing the Trade-goods.plist and deprecating the commodities.plist] (2014)
{{QuoteText|Text=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.|Source=([https://bb.oolite.space/viewtopic.php?p=226722#p226722 Cim in Progress Thread (2014)])}}
=== Using the Trade-goods.plist ===
*[https://bb.oolite.space/viewtopic.php?f=4&t=20576 How to get the displayName for a commodity in the Main Station Market?] (2020)
*[https://bb.oolite.space/viewtopic.php?f=6&t=17269 Thinking about Planet Income classification] (2015)

{{QuoteText|Text=
In 1.81 this is a lot easier to OXP - you can introduce as many economies as you like, though you are limited to eight economy symbols (so if you wanted lots of economy types, you might end up with Poor Industrial, Avg Industrial and Rich Industrial sharing a symbol on the map). The trade good pricing scripts can then be used to set up different price categories in different economies (and introduce additional trade goods, or split an existing good into multiple categories, which may be necessary if you're adding more economies).

Resetting economies across the planets is a big change in terms of lines of code, but is also very easy to automate. If OXPers are looking for a scripting tool to use for this sort of automation, then NodeJS or io.js is free and also uses Javascript as its language, so you don't need to learn a new one - and may even be able to share code between your build scripts and your OXP, though I haven't tried that yet.|Source=([https://bb.oolite.space/viewtopic.php?f=6&t=17269 Cim in Planet Income thread (2015)])}}

[[Category:Oolite]]
[[Category:Oolite scripting]]

Trade-goods (abridged)

2026-06-18T09:43:08Z

Wildeblood: /* Preamble */ Improved.

'''You are probably looking for [[Trade-goods.plist]]''', rather than this page.

== Preamble ==

The trade-goods.plist file defines "trade goods" (commodities/cargo). But, it does not ''e.g.'' remove slaves from a particular station or make them cost twice as much as they do at the main orbital station. To do such things, ''i.e.'' to tweak the pricing/availability of commodities in a particular station, you need to define the market inside that station, either within its [[Shipdata.plist]] or within a [[Oolite_Market_Scripts|Oolite Market Script]] linked from its shipdata.plist.

== Overview ==

The Trade-goods.plist 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 [[Oolite_JavaScript_Reference:_Manifest#setComment|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 [[Oolite Market Scripts|market script]] for this trade good when calculating main station quantities and prices.

'''Note:''' [https://bb.oolite.space/viewtopic.php?p=235837#p235837 What's the difference between the market script specified in planetinfo.plist and the one called for by trade-goods.plist?] (2015)

=== name ===
A string containing the name of the trade good. This may contain [keys]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 [[Oolite_JavaScript_Reference:_Manifest#setShortComment|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 ==

The Primary market is that of the main orbital station of the system. The Secondary markets are other station/dockable markets (which are influenced by the primary market), ''eg'' that of a local Rock Hermit, or a visiting liner or another orbital station. Both quantities and prices will be influenced by those of the primary market. Needless to say, the primary market is randomly recalculated each time the system is visited.

Secondary market definitions are entered in the [[shipdata.plist#market_definition|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:

# The market definition array is searched from top to bottom for the first element matching the trade good
# The market quantity is scaled in proportion to the relative capacities for that good in the two markets.
# 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|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 [[shipdata.plist#market_capacity|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 [[shipdata.plist#market_monitored|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.

=== Links ===
*[https://bb.oolite.space/viewtopic.php?f=2&t=21512 Secondary Market Definitions Defined] (2023)

== 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 for determining markets for new stations.

=== From the vanilla game: Rock Hermits ===
The "market_definition" 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: the Trade-goods.plist updated from the original 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;
};

}
=== A new commodity (from the Trade-goods.plist inside "SW Economy") ===
"medicine" = {
"name" = "[commodity-name medicine]";
"classes" = ("oolite-consumer","oolite-medical");
"quantity_unit" = 1;
"peak_export" = 7;
"peak_import" = 0;
"price_average" = 640;
"price_economic" = 0.25;
"price_random" = 0.15;
"quantity_average" = 5;
"quantity_economic" = 1.5;
"quantity_random" = 1.0;
"legality_export" = 0;
"legality_import" = 0;
"trumble_opinion" = 0.50;
"sort_order" = 500;
"comment" = "[oolite-commodity-medicine]";
};

=== Setting an orbital main station's slaves on sale to zero ===
[[User:Phkb|Phkb]] provided this example which requires a ''planetinfo.plist'' & a new ''.js file'' - there are other ways to achieve the same result
==== 1) planetinfo.plist (to invoke the market script) ====
(in the "Config" folder)

{
"0 96" = {market_script = "digebiti_noslaves.js";};
}

==== 2) Market script: digebiti_noslaves.js ====
(in the "Scripts" folder) - note the complex name, which prevents confusion with other snippets of script

"use strict";
this.name = "digebiti_noslaves";
this.author = "Phkb";
this.copyright = "(C) 2022 Phkb";
this.licence = "CC-NC-by-SA 4.0";
this.description = "Removes slaves for sale in Digebiti";
this.version = "1.0";

this.updateLocalCommodityDefinition = function(goodDefinition, station, systemID) {
if (goodDefinition.key == "slaves" && station && station.isMainStation) {
goodDefinition.quantity = 0;
}
return goodDefinition;
}

This method will work, so long as no other OXP changes the market_script property of the Digebiti system in the same way.

=== Creating an invariant market independent of the local system economy (agricultural/industrial) ===
If you just use a market_definition in shipdata.plist for the station, then you're merely setting variations on the primary system market.

If you want the station prices to be independent of (or more loosely tied to) the system it's in, then you need to use a [[Oolite_Market_Scripts|market script]].

So what you'd have is something like this - let's say it's a hydroponics station, so it always sells food and nothing else, regardless of whether the general system economy is industrial or agricultural:

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.key == "food") {
// are we calculating the basic Oolite "food" trade good right now? If yes, set our own static prices
goodDefinition.price = 25; // 2.5 credits
goodDefinition.quantity = 80; // lots of food
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

Now ... the reason that market definitions are preferred to be mutators of the system economy is for two reasons.
1) it means you can avoid the situation where you end up with two adjacent stations with wildly different prices ... but you can of course handle that in other ways too, station positioning, restricted access, ''etc''.
2) it makes it easier to handle OXP trade goods:
- other OXPs might have added more "food" type goods, ''e.g.'' "Meat" or "Cheese"
- you can learn about those and handle them specifically

} else if (goodDefinition.key == "bobsfoodoxp_cheese") {
// set price and quantity here

... but that means a lot of keeping up with what everyone else is doing with custom goods.

The idea was that for your hydroponics station what you might do instead is something like this

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So now if another OXP adds Cheese, provided they declare it as "edible", your station will sell it in high quantities at a big discount, but you don't need to know exactly what the baseline price or quantity was set - so if a food-focused OXP was to add "Wine", "Fine Wine" and "Vintage Wine" at a range of prices and quantities, you'd be automatically handling those in reasonable line with a combination of the Wine OXP's basic pricing structure and your station OXP's "food primary source market" style, without necessarily needing to know about every future Wine OXP there might be and explicitly set compatibility.

Note in this example we're still zeroing out all non-food goods - OXP included! - regardless of the local economy. Maybe at this point we'd want to include and document a "hydroponicsoxp-agriculturalequipment" trade good class that other OXPs could use, which this station would buy up at higher demand and prices than normal.

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else if (goodDefinition.classes.indexOf("hydroponicsoxp-agriculturalequipment") >= 0) {
// custom class for other OXPs to add specific agricultural equipment e.g. combine harvesters, compost, fertiliser
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.capacity = 16; // buy a small amount only // TODO: raise capacity if price per tonne is low
goodDefinition.quantity = 0; // not selling this
} else if (goodDefinition.key == "machinery") {
// the basic Oolite Machinery commodity isn't in the custom class but we need to buy something if
// no OXPs adding it are installed
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.quantity = 0; // not selling
goodDefinition.capacity = 16; // small capacity to buy
} else {
// don't buy or sell any other commodity
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So you can see this one has a mix of using, mutating and overruling the definitions set by the system market and OXP commodity definitions ... with this method you could have a whole bunch of OXPs setting up themed stations, and a whole different bunch adding their own custom commodities, and they'd barely have to know about each other to ensure reasonable consistency and compatibility from someone installing any combination of them. (- by [[User:Cim|Cim]], 2023)

Note: this gives examples for 1 commodity at a time, but not how to easily do that for ALL the commodities on ALL the extra stations in a system.

== Using the new Trade-goods.plist ==
The original commodities.plist was really not very good - it was based very strongly on the original Elite 84 pricing algorithm, which was written to use peculiarities of 8-bit Maths to its advantage. So one ended up with a series of fairly incomprehensible integers defining each market.

The trade-goods.plist was designed to make that simpler, by:
:1) Making it a dictionary rather than an unlabelled array so one could tell which parameter was which
:2) Making the price range for a trade good dependent on more sensible variables, so rather than setting the price range with a bitmask, one set the price and quantity variations dependent on the economy and on random chance.

Compare the v.1.81 trade-goods.plist with a v.1.80 commodities.plist - they were designed to give near-identical market behaviour for the built-in trade goods.

But - that only made it more comprehensible. It didn't really let one do anything particularly different to Elite 84 markets - mostly including the "Rich Industrial -> Poor Agricultural" single spectrum. One can tweak that a bit with peak_export and peak_import to get slightly different shapes (so a good might peak at Poor Industrial rather than Rich Industrial) but it doesn't really give one the option of a third economy type still.

''So how does one introduce a new economic pole, such as a mining industry?''

For that, one needs the scripting support. [[Oolite JavaScript Reference: Market Scripts]]. 
One can quite literally do whatever one likes with the prices that way. One could have every *system* have its own separate economy, which varied over time according to events, what the player had previously traded, ''etc. etc.'' to produce something comparable to Elite Dangerous' economic sim, if that's the route one wanted to go down. Obviously the more complexity one adds the harder it gets to script up, but it's now all possible.

[[File:SOTL Altmap F8.png|thumb|right|200px|SOTL Altmap F8 commodities market]]
[[SOTL Altmap]] does have an example of it, which basically throws out the original Elite-like algorithm of trade-goods.plist and starts over. It goes *way* beyond just adding a third economy, too.

Basically in SOTL every trade good is tagged in the trade-goods.plist with a bunch of classes
''e.g.''
classes = ("sotl-ex-salvage","sotl-im-refining","sotl-quantity-high","sotl-priceband-3","sotl-demand-medium","sotl-supply-medium","sotl-volatility-low");
So that means:
- exported by salvage economies
- imported by refining economies
- high quantity, moderate price, low price volatility

Then the market script uses those classes, rather than the standard pricing variables, to define the economic behaviour.
:So line 69-74ish: get the current economy description, convert that to the format used in the class name
:...line 85-90: check for the import and export classes for that economy and see if it's imported or exported
:...lines 100-120: apply various special conditions, so e.g. the sotl-ims-radiation class checks the planet surface radiation levels (custom property in sysinfo) and if the radiation level is high, imports these goods even if the basic economy isn't interested (e.g. "sotl-ceramics-ind" in the plist)
:...and then it uses those calculations (and a bunch more of the classes) in the rest of the script to set the price and quantity depending on whether it's an import, an export, or neither

That's massive overkill for just adding a third mining economy, but one would need to work on a similar principle.

:1) Tag every commodity with classes for (import|export|none)-(agricultural|industrial|mining) as appropriate
:2) Adjust the economy names (there are a few different ways one could do that) so that the 8 economy IDs were allocated to agricultural, industrial and mining economies
:3) Have a price script which like the SOTL one gets the current economy, looks at the classes list to find out if the commodity is imported or exported or neither, and sets the price and quantity accordingly. One could use the standard price_economic, price_average, price_random properties in the plist to give baseline data to the script if one was not planning to do anything too weird.

{Technically one doesn't need the classes - just have the price script contain a list of goods internally for each economy - but this way if other people add extra trade goods in their own OXPs, they can tag them up for mining economy support too}

All fairly straightforward theoretically.

''The biggest impediment to doing a wholesale reworking of the economic system, is just how incompatible it makes lots and lots of OXP's. In order to override the vanilla commodities as in SOTL, requires setting a script for each in trade-goods.plist. Which is fine if it's the only OXP that wants to play around with commodity prices. As soon as two OXP's try to do the same thing, one gets a conflict and no longer knows which OXP pricing model is in play.''

''For SOTL it's fine, because it uses the scenario system to forcibly eject all other OXP's from use while it's running. But if one wants the OXP to go in the general playing pool set of OXP's, it becomes much more complicated. [[User:Phkb|Phkb]] spent a long time trying to work out why his market script wasn't running, only to find that [[UPS Courier]] was quietly adjusting the markets in certain systems via the planetinfo.plist file. And there are a lot of OXP's that want to play in this space, tweaking prices up or down.''

''Hence one usually abandons using any of the script options, and just tweaks the price after all the scripts have finished playing, ''eg'' in [[Smugglers]]. It was the only way to guarantee getting some sort of bump in a price when wanted.''

== Links ==
*[[Oolite JavaScript Reference: Market Scripts]]
*[[Commodities.plist]] - the precursor (which still mostly works!). If it doesn't see [https://bb.oolite.space/viewtopic.php?p=246145#p246145 here] (2015)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16828 Proposal for 1.82: support for economic changes] ([[User:Cim|Cim]], 2014)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16735 Cim on introducing the Trade-goods.plist and deprecating the commodities.plist] (2014)
{{QuoteText|Text=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.|Source=([https://bb.oolite.space/viewtopic.php?p=226722#p226722 Cim in Progress Thread (2014)])}}
=== Using the Trade-goods.plist ===
*[https://bb.oolite.space/viewtopic.php?f=4&t=20576 How to get the displayName for a commodity in the Main Station Market?] (2020)
*[https://bb.oolite.space/viewtopic.php?f=6&t=17269 Thinking about Planet Income classification] (2015)

{{QuoteText|Text=
In 1.81 this is a lot easier to OXP - you can introduce as many economies as you like, though you are limited to eight economy symbols (so if you wanted lots of economy types, you might end up with Poor Industrial, Avg Industrial and Rich Industrial sharing a symbol on the map). The trade good pricing scripts can then be used to set up different price categories in different economies (and introduce additional trade goods, or split an existing good into multiple categories, which may be necessary if you're adding more economies).

Resetting economies across the planets is a big change in terms of lines of code, but is also very easy to automate. If OXPers are looking for a scripting tool to use for this sort of automation, then NodeJS or io.js is free and also uses Javascript as its language, so you don't need to learn a new one - and may even be able to share code between your build scripts and your OXP, though I haven't tried that yet.|Source=([https://bb.oolite.space/viewtopic.php?f=6&t=17269 Cim in Planet Income thread (2015)])}}

[[Category:Oolite]]
[[Category:Oolite scripting]]

Trade-goods (abridged)

2026-06-18T08:22:49Z

Wildeblood: Starting page created.

'''You are probably looking for [[Trade-goods.plist]]''', rather than this page.

== Preamble ==
This merely re-defines the trade commodities in the game (''eg'' introducing new ones, or changing elements of the vanilla game ones). See [[SW Economy]] for an example of what can be done.

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. But it does not remove slaves from a particular station or make them cost twice as much as they do at the main orbital station.

To do other things, ''eg''. to tweak the pricing/availability of commodities in a particular station, you need to define the market inside that station's [[Shipdata.plist]] - or include a "hook" inside that shipdata.plist to a javascript [[Oolite_Market_Scripts|Oolite Market Script]] (which allows more complex definitions).

== Overview ==

The Trade-goods.plist 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 [[Oolite_JavaScript_Reference:_Manifest#setComment|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 [[Oolite Market Scripts|market script]] for this trade good when calculating main station quantities and prices.

'''Note:''' [https://bb.oolite.space/viewtopic.php?p=235837#p235837 What's the difference between the market script specified in planetinfo.plist and the one called for by trade-goods.plist?] (2015)

=== name ===
A string containing the name of the trade good. This may contain [keys]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 [[Oolite_JavaScript_Reference:_Manifest#setShortComment|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 ==

The Primary market is that of the main orbital station of the system. The Secondary markets are other station/dockable markets (which are influenced by the primary market), ''eg'' that of a local Rock Hermit, or a visiting liner or another orbital station. Both quantities and prices will be influenced by those of the primary market. Needless to say, the primary market is randomly recalculated each time the system is visited.

Secondary market definitions are entered in the [[shipdata.plist#market_definition|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:

# The market definition array is searched from top to bottom for the first element matching the trade good
# The market quantity is scaled in proportion to the relative capacities for that good in the two markets.
# 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|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 [[shipdata.plist#market_capacity|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 [[shipdata.plist#market_monitored|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.

=== Links ===
*[https://bb.oolite.space/viewtopic.php?f=2&t=21512 Secondary Market Definitions Defined] (2023)

== 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 for determining markets for new stations.

=== From the vanilla game: Rock Hermits ===
The "market_definition" 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: the Trade-goods.plist updated from the original 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;
};

}
=== A new commodity (from the Trade-goods.plist inside "SW Economy") ===
"medicine" = {
"name" = "[commodity-name medicine]";
"classes" = ("oolite-consumer","oolite-medical");
"quantity_unit" = 1;
"peak_export" = 7;
"peak_import" = 0;
"price_average" = 640;
"price_economic" = 0.25;
"price_random" = 0.15;
"quantity_average" = 5;
"quantity_economic" = 1.5;
"quantity_random" = 1.0;
"legality_export" = 0;
"legality_import" = 0;
"trumble_opinion" = 0.50;
"sort_order" = 500;
"comment" = "[oolite-commodity-medicine]";
};

=== Setting an orbital main station's slaves on sale to zero ===
[[User:Phkb|Phkb]] provided this example which requires a ''planetinfo.plist'' & a new ''.js file'' - there are other ways to achieve the same result
==== 1) planetinfo.plist (to invoke the market script) ====
(in the "Config" folder)

{
"0 96" = {market_script = "digebiti_noslaves.js";};
}

==== 2) Market script: digebiti_noslaves.js ====
(in the "Scripts" folder) - note the complex name, which prevents confusion with other snippets of script

"use strict";
this.name = "digebiti_noslaves";
this.author = "Phkb";
this.copyright = "(C) 2022 Phkb";
this.licence = "CC-NC-by-SA 4.0";
this.description = "Removes slaves for sale in Digebiti";
this.version = "1.0";

this.updateLocalCommodityDefinition = function(goodDefinition, station, systemID) {
if (goodDefinition.key == "slaves" && station && station.isMainStation) {
goodDefinition.quantity = 0;
}
return goodDefinition;
}

This method will work, so long as no other OXP changes the market_script property of the Digebiti system in the same way.

=== Creating an invariant market independent of the local system economy (agricultural/industrial) ===
If you just use a market_definition in shipdata.plist for the station, then you're merely setting variations on the primary system market.

If you want the station prices to be independent of (or more loosely tied to) the system it's in, then you need to use a [[Oolite_Market_Scripts|market script]].

So what you'd have is something like this - let's say it's a hydroponics station, so it always sells food and nothing else, regardless of whether the general system economy is industrial or agricultural:

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.key == "food") {
// are we calculating the basic Oolite "food" trade good right now? If yes, set our own static prices
goodDefinition.price = 25; // 2.5 credits
goodDefinition.quantity = 80; // lots of food
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

Now ... the reason that market definitions are preferred to be mutators of the system economy is for two reasons.
1) it means you can avoid the situation where you end up with two adjacent stations with wildly different prices ... but you can of course handle that in other ways too, station positioning, restricted access, ''etc''.
2) it makes it easier to handle OXP trade goods:
- other OXPs might have added more "food" type goods, ''e.g.'' "Meat" or "Cheese"
- you can learn about those and handle them specifically

} else if (goodDefinition.key == "bobsfoodoxp_cheese") {
// set price and quantity here

... but that means a lot of keeping up with what everyone else is doing with custom goods.

The idea was that for your hydroponics station what you might do instead is something like this

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else {
// if not, don't buy or sell any other commodity
// TODO: work out what we should import
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So now if another OXP adds Cheese, provided they declare it as "edible", your station will sell it in high quantities at a big discount, but you don't need to know exactly what the baseline price or quantity was set - so if a food-focused OXP was to add "Wine", "Fine Wine" and "Vintage Wine" at a range of prices and quantities, you'd be automatically handling those in reasonable line with a combination of the Wine OXP's basic pricing structure and your station OXP's "food primary source market" style, without necessarily needing to know about every future Wine OXP there might be and explicitly set compatibility.

Note in this example we're still zeroing out all non-food goods - OXP included! - regardless of the local economy. Maybe at this point we'd want to include and document a "hydroponicsoxp-agriculturalequipment" trade good class that other OXPs could use, which this station would buy up at higher demand and prices than normal.

// this is going to get called once for each trade good on the market
function updateLocalCommodityDefinition (goodDefinition, station, system) {
// at this point, goodDefinition will contain the trade-goods.plist information on the commodity itself
// and a price and quantity key to say what the processing so far has done in mutating the default system market
// so that might say "price" = 35; "quantity" = 50;
// the important thing is that we can just ignore that entirely if we want
if (goodDefinition.classes.indexOf("oolite-edible") >= 0) {
// has this commodity been declared either by Oolite Core or by the OXP that added it as
// some sort of food?
goodDefinition.price = goodDefinition.price * 0.6; // big discount for buying at source
goodDefinition.quantity = 10 + (goodDefinition.quantity * 2); // lots of it, and at least 10t even in heavily industrial systems
} else if (goodDefinition.classes.indexOf("hydroponicsoxp-agriculturalequipment") >= 0) {
// custom class for other OXPs to add specific agricultural equipment e.g. combine harvesters, compost, fertiliser
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.capacity = 16; // buy a small amount only // TODO: raise capacity if price per tonne is low
goodDefinition.quantity = 0; // not selling this
} else if (goodDefinition.key == "machinery") {
// the basic Oolite Machinery commodity isn't in the custom class but we need to buy something if
// no OXPs adding it are installed
goodDefinition.price = goodDefinition.price * 1.3; // better prices here
goodDefinition.quantity = 0; // not selling
goodDefinition.capacity = 16; // small capacity to buy
} else {
// don't buy or sell any other commodity
goodDefinition.price = 0;
goodDefinition.quantity = 0;
goodDefinition.capacity = 0;
}
return goodDefinition;
}

So you can see this one has a mix of using, mutating and overruling the definitions set by the system market and OXP commodity definitions ... with this method you could have a whole bunch of OXPs setting up themed stations, and a whole different bunch adding their own custom commodities, and they'd barely have to know about each other to ensure reasonable consistency and compatibility from someone installing any combination of them. (- by [[User:Cim|Cim]], 2023)

Note: this gives examples for 1 commodity at a time, but not how to easily do that for ALL the commodities on ALL the extra stations in a system.

== Using the new Trade-goods.plist ==
The original commodities.plist was really not very good - it was based very strongly on the original Elite 84 pricing algorithm, which was written to use peculiarities of 8-bit Maths to its advantage. So one ended up with a series of fairly incomprehensible integers defining each market.

The trade-goods.plist was designed to make that simpler, by:
:1) Making it a dictionary rather than an unlabelled array so one could tell which parameter was which
:2) Making the price range for a trade good dependent on more sensible variables, so rather than setting the price range with a bitmask, one set the price and quantity variations dependent on the economy and on random chance.

Compare the v.1.81 trade-goods.plist with a v.1.80 commodities.plist - they were designed to give near-identical market behaviour for the built-in trade goods.

But - that only made it more comprehensible. It didn't really let one do anything particularly different to Elite 84 markets - mostly including the "Rich Industrial -> Poor Agricultural" single spectrum. One can tweak that a bit with peak_export and peak_import to get slightly different shapes (so a good might peak at Poor Industrial rather than Rich Industrial) but it doesn't really give one the option of a third economy type still.

''So how does one introduce a new economic pole, such as a mining industry?''

For that, one needs the scripting support. [[Oolite JavaScript Reference: Market Scripts]]. 
One can quite literally do whatever one likes with the prices that way. One could have every *system* have its own separate economy, which varied over time according to events, what the player had previously traded, ''etc. etc.'' to produce something comparable to Elite Dangerous' economic sim, if that's the route one wanted to go down. Obviously the more complexity one adds the harder it gets to script up, but it's now all possible.

[[File:SOTL Altmap F8.png|thumb|right|200px|SOTL Altmap F8 commodities market]]
[[SOTL Altmap]] does have an example of it, which basically throws out the original Elite-like algorithm of trade-goods.plist and starts over. It goes *way* beyond just adding a third economy, too.

Basically in SOTL every trade good is tagged in the trade-goods.plist with a bunch of classes
''e.g.''
classes = ("sotl-ex-salvage","sotl-im-refining","sotl-quantity-high","sotl-priceband-3","sotl-demand-medium","sotl-supply-medium","sotl-volatility-low");
So that means:
- exported by salvage economies
- imported by refining economies
- high quantity, moderate price, low price volatility

Then the market script uses those classes, rather than the standard pricing variables, to define the economic behaviour.
:So line 69-74ish: get the current economy description, convert that to the format used in the class name
:...line 85-90: check for the import and export classes for that economy and see if it's imported or exported
:...lines 100-120: apply various special conditions, so e.g. the sotl-ims-radiation class checks the planet surface radiation levels (custom property in sysinfo) and if the radiation level is high, imports these goods even if the basic economy isn't interested (e.g. "sotl-ceramics-ind" in the plist)
:...and then it uses those calculations (and a bunch more of the classes) in the rest of the script to set the price and quantity depending on whether it's an import, an export, or neither

That's massive overkill for just adding a third mining economy, but one would need to work on a similar principle.

:1) Tag every commodity with classes for (import|export|none)-(agricultural|industrial|mining) as appropriate
:2) Adjust the economy names (there are a few different ways one could do that) so that the 8 economy IDs were allocated to agricultural, industrial and mining economies
:3) Have a price script which like the SOTL one gets the current economy, looks at the classes list to find out if the commodity is imported or exported or neither, and sets the price and quantity accordingly. One could use the standard price_economic, price_average, price_random properties in the plist to give baseline data to the script if one was not planning to do anything too weird.

{Technically one doesn't need the classes - just have the price script contain a list of goods internally for each economy - but this way if other people add extra trade goods in their own OXPs, they can tag them up for mining economy support too}

All fairly straightforward theoretically.

''The biggest impediment to doing a wholesale reworking of the economic system, is just how incompatible it makes lots and lots of OXP's. In order to override the vanilla commodities as in SOTL, requires setting a script for each in trade-goods.plist. Which is fine if it's the only OXP that wants to play around with commodity prices. As soon as two OXP's try to do the same thing, one gets a conflict and no longer knows which OXP pricing model is in play.''

''For SOTL it's fine, because it uses the scenario system to forcibly eject all other OXP's from use while it's running. But if one wants the OXP to go in the general playing pool set of OXP's, it becomes much more complicated. [[User:Phkb|Phkb]] spent a long time trying to work out why his market script wasn't running, only to find that [[UPS Courier]] was quietly adjusting the markets in certain systems via the planetinfo.plist file. And there are a lot of OXP's that want to play in this space, tweaking prices up or down.''

''Hence one usually abandons using any of the script options, and just tweaks the price after all the scripts have finished playing, ''eg'' in [[Smugglers]]. It was the only way to guarantee getting some sort of bump in a price when wanted.''

== Links ==
*[[Oolite JavaScript Reference: Market Scripts]]
*[[Commodities.plist]] - the precursor (which still mostly works!). If it doesn't see [https://bb.oolite.space/viewtopic.php?p=246145#p246145 here] (2015)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16828 Proposal for 1.82: support for economic changes] ([[User:Cim|Cim]], 2014)
*[https://bb.oolite.space/viewtopic.php?f=2&t=16735 Cim on introducing the Trade-goods.plist and deprecating the commodities.plist] (2014)
{{QuoteText|Text=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.|Source=([https://bb.oolite.space/viewtopic.php?p=226722#p226722 Cim in Progress Thread (2014)])}}
=== Using the Trade-goods.plist ===
*[https://bb.oolite.space/viewtopic.php?f=4&t=20576 How to get the displayName for a commodity in the Main Station Market?] (2020)
*[https://bb.oolite.space/viewtopic.php?f=6&t=17269 Thinking about Planet Income classification] (2015)

{{QuoteText|Text=
In 1.81 this is a lot easier to OXP - you can introduce as many economies as you like, though you are limited to eight economy symbols (so if you wanted lots of economy types, you might end up with Poor Industrial, Avg Industrial and Rich Industrial sharing a symbol on the map). The trade good pricing scripts can then be used to set up different price categories in different economies (and introduce additional trade goods, or split an existing good into multiple categories, which may be necessary if you're adding more economies).

Resetting economies across the planets is a big change in terms of lines of code, but is also very easy to automate. If OXPers are looking for a scripting tool to use for this sort of automation, then NodeJS or io.js is free and also uses Javascript as its language, so you don't need to learn a new one - and may even be able to share code between your build scripts and your OXP, though I haven't tried that yet.|Source=([https://bb.oolite.space/viewtopic.php?f=6&t=17269 Cim in Planet Income thread (2015)])}}

[[Category:Oolite]]
[[Category:Oolite scripting]]

File:Distant Riches.png

2026-06-16T15:58:14Z

Wildeblood: OXP cover art

== Summary ==
OXP cover art

Docked HUDs

2026-06-16T13:27:28Z

Wildeblood:

Sleek, minimalist HUD design when docked. If you use a HUD expansion pack, instead of the standard HUD, check the forum for compatibility notes. The newest version (see at bottom) also acts as an immersive introduction to the complexities of Oolite for new players.

== Overview ==
Replaces the HUD of your choice while docked with a minimal HUD showing only
*fuel gauge (in case you need to refuel)
*missile display (in case you need to buy more)
The rest is banished until you launch!

Note: some HUDs do this automatically without the need for this OXP.

== Downloads ==

=== Modularized version ===

Version 1.5 will come in 3 components:

Svelte original: [[File:Docked HUDs.oxz]]
Function labels: [[File:Docked HUDs data sources.oxz]]
Special effects: [[File:Docked HUDs extras.oxz]]

=== Version 1.4 ===

Recent bloatware: [[File:Docked HUDs.oxz]]

=== Version 1.1 ===

Svelte original: [[File:Wildefire Docked HUDs 1.1.oxz]]

== License ==
*License: CC-BY-NC-SA 4.0
*Author: [[User:Wildeblood|Wildeblood]]
*Version: 1.4.3
*Required Oolite Version: 1.80

== Tweaking ==
{{QuoteText|Text=You'll find the fuel bar helpful. I used to have a Docked HUDs OXP with three HUD files. One had the fuel bar, one the missile display, and the last the missile display, very faint (opacity 20% IIRC). There was nothing else on them except the clock, and in later versions the commlog position.
... Anyway, becoming relevant, I used guiScreenChanged & playerBoughtEquipment, rather than shipDockedWithStation & shipWillLaunchFromStation (which were used by my main HUD), so it was immune to interference by my main HUD script. It first checked player.ship.docked (Do I really need to say that?), then the fuel and, if necessary, missile count and selected need-fuel-hud.plist, need-missiles-hud.plist or missiles-full-hud.plist (a.k.a. need nothing).

To any non-forum-members reading along, I recommend this as a ''my first OXP'' exercise. The script is simple, the HUD files are ridiculously simple, the result looks fairly slick, and putting it all together is just tedious enough to leave you feeling satisfied when you finish!|Source=([https://bb.oolite.space/viewtopic.php?p=231734#p231734 Wildeblood])}}

*See [[How to tweak OXZ's]] for more information on general tweaking

== Links ==
*[https://bb.oolite.space/viewtopic.php?f=4&t=17217 BB Thread] (2015+)
*[[HUD]]

== Gameplay and Balance Indicator ==
[[File:Tag-colour-green.png|right]]
Great for the aesthetics - but less relevant for gameplay balance!

{{HUD-OXP}}

Docked HUDs

2026-06-16T13:18:08Z

Wildeblood: /* License */

Sleek, minimalist HUD design when docked. If you use a HUD expansion pack, instead of the standard HUD, check the forum for compatibility notes.

the newest version (see at bottom) also acts as an immersive introduction to the complexities of Oolite for new players.

== Overview ==
Replaces the HUD of your choice while docked with a minimal HUD showing only
*fuel gauge (in case you need to refuel)
*missile display (in case you need to buy more)
The rest is banished until you launch!

Note: some HUDs do this automatically without the need for this OXP.

== Downloads ==

=== Modularized version ===

Version 1.5 will come in 3 components:

Svelte original: [[File:Docked HUDs.oxz]]
Function labels: [[File:Docked HUDs data sources.oxz]]
Special effects: [[File:Docked HUDs extras.oxz]]

=== Version 1.4 ===

Recent bloatware: [[File:Docked HUDs.oxz]]

=== Version 1.1 ===

Svelte original: [[File:Wildefire Docked HUDs 1.1.oxz]]

== License ==
*License: CC-BY-NC-SA 4.0
*Author: [[User:Wildeblood|Wildeblood]]
*Version: 1.4.3
*Required Oolite Version: 1.80

== Tweaking ==
{{QuoteText|Text=You'll find the fuel bar helpful. I used to have a Docked HUDs OXP with three HUD files. One had the fuel bar, one the missile display, and the last the missile display, very faint (opacity 20% IIRC). There was nothing else on them except the clock, and in later versions the commlog position.
... Anyway, becoming relevant, I used guiScreenChanged & playerBoughtEquipment, rather than shipDockedWithStation & shipWillLaunchFromStation (which were used by my main HUD), so it was immune to interference by my main HUD script. It first checked player.ship.docked (Do I really need to say that?), then the fuel and, if necessary, missile count and selected need-fuel-hud.plist, need-missiles-hud.plist or missiles-full-hud.plist (a.k.a. need nothing).

To any non-forum-members reading along, I recommend this as a ''my first OXP'' exercise. The script is simple, the HUD files are ridiculously simple, the result looks fairly slick, and putting it all together is just tedious enough to leave you feeling satisfied when you finish!|Source=([https://bb.oolite.space/viewtopic.php?p=231734#p231734 Wildeblood])}}

*See [[How to tweak OXZ's]] for more information on general tweaking

== Links ==
*[https://bb.oolite.space/viewtopic.php?f=4&t=17217 BB Thread] (2015+)
*[[HUD]]

== Gameplay and Balance Indicator ==
[[File:Tag-colour-green.png|right]]
Great for the aesthetics - but less relevant for gameplay balance!

{{HUD-OXP}}

Docked HUDs

2026-06-16T13:17:20Z

Wildeblood: /* Downloads */

Sleek, minimalist HUD design when docked. If you use a HUD expansion pack, instead of the standard HUD, check the forum for compatibility notes.

the newest version (see at bottom) also acts as an immersive introduction to the complexities of Oolite for new players.

== Overview ==
Replaces the HUD of your choice while docked with a minimal HUD showing only
*fuel gauge (in case you need to refuel)
*missile display (in case you need to buy more)
The rest is banished until you launch!

Note: some HUDs do this automatically without the need for this OXP.

== Downloads ==

=== Modularized version ===

Version 1.5 will come in 3 components:

Svelte original: [[File:Docked HUDs.oxz]]
Function labels: [[File:Docked HUDs data sources.oxz]]
Special effects: [[File:Docked HUDs extras.oxz]]

=== Version 1.4 ===

Recent bloatware: [[File:Docked HUDs.oxz]]

=== Version 1.1 ===

Svelte original: [[File:Wildefire Docked HUDs 1.1.oxz]]

== License ==
*License: CC-BY-NC-SA 3.0
*Author: [[User:Wildeblood|Wildeblood]]
*Version: 1.4.2
*Required Oolite Version: 1.80

== Tweaking ==
{{QuoteText|Text=You'll find the fuel bar helpful. I used to have a Docked HUDs OXP with three HUD files. One had the fuel bar, one the missile display, and the last the missile display, very faint (opacity 20% IIRC). There was nothing else on them except the clock, and in later versions the commlog position.
... Anyway, becoming relevant, I used guiScreenChanged & playerBoughtEquipment, rather than shipDockedWithStation & shipWillLaunchFromStation (which were used by my main HUD), so it was immune to interference by my main HUD script. It first checked player.ship.docked (Do I really need to say that?), then the fuel and, if necessary, missile count and selected need-fuel-hud.plist, need-missiles-hud.plist or missiles-full-hud.plist (a.k.a. need nothing).

To any non-forum-members reading along, I recommend this as a ''my first OXP'' exercise. The script is simple, the HUD files are ridiculously simple, the result looks fairly slick, and putting it all together is just tedious enough to leave you feeling satisfied when you finish!|Source=([https://bb.oolite.space/viewtopic.php?p=231734#p231734 Wildeblood])}}

*See [[How to tweak OXZ's]] for more information on general tweaking

== Links ==
*[https://bb.oolite.space/viewtopic.php?f=4&t=17217 BB Thread] (2015+)
*[[HUD]]

== Gameplay and Balance Indicator ==
[[File:Tag-colour-green.png|right]]
Great for the aesthetics - but less relevant for gameplay balance!

{{HUD-OXP}}

AI Trading Backup Datalogger

2026-06-16T12:51:01Z

Wildeblood: /* Summary */ Yes, summary.

This OXP records your transactions on the F8 screen for later use by the [[AI Trading Assistant]]

Does what it says - quietly logs data, while being invisible in-game. You install this alongside the main OXP, then forget about it. When you want to try out Market Observer OXP, you remove AI Trading Assistant OXP, but leave the backup logger. When you realize you've made a horrible mistake, you put AI Trading Assistant OXP back, remove Market Observer OXP, and (like magic!) there's no gap in your data. Everything carries on as though you had never strayed. ("It's alright, Pam, it was just a dream.")

Author: [[User:Wildeblood]]

Download: [[File:AI Trading Backup Datalogger 3.oxz]] (June 2026)

Links: [https://bb.oolite.space/viewtopic.php?p=293796#p293796 Discussion (2024)]

{{misc-OXP}}

User:Wildeblood

2026-06-16T01:22:57Z

Wildeblood:

[[File:Distant Thunder album cover.png|thumb|right|500px|Miss Sexy Voice announces goings on, and thunderous hyperspace sound.]]
[[File:Very Advanced Space Compass album cover.png|thumb|right|500px|It's the space compass, Jim, but not as we know it.]]
[[File:World Builder cover art.png|thumb|right|500px|Rule the Ooniverse your way!]]
[[File:Galactic_Hyperdrive_icon.png|thumb|right|500px|Galactic Hyperdrive programmers, because knowing where you're going...]]
[[File:Retro-Encabulator album cover.png|thumb|right|500px|You know it makes sense!]]
[[File:Distant Suns album cover.png|thumb|right|500px|The original Distant Suns OXP.]]
[[File:Trading Assistant album cover.png|thumb|right|500px|The original and genuine!]]
[[File:Distant Voyages cover art.png|thumb|right|500px|Rediscover the Galaxy]]
[[File:SE-X Drive album cover.png|thumb|right|500px|Special Equipment (Experimental)]]
[[File:Polarity_Reverser_cover_art.png|thumb|right|500px|Plasma conduits are especially reversible.]]
[[File:Distant Realms cover art.png|thumb|right|500px|Who's in charge around here?]]
[[File:Psionic Broadcaster.png|thumb|right|500px|Dynooverse Research really want to know how you feel.]]
[[File:Witch Bank.png|thumb|right|500px|More trustworthy than Westpac.]]
[[File:AristoShares_cover_art.png|thumb|right|500px|Stockbroker to the Stars]]

== Trinkets ==
==== Latest (A.D. 2026) trinkets ====
[[File:AristoShares.oxz]]
[[File:Docked_HUDs.oxz]]
[[File:Docked HUDs data sources.oxz]]
[[File:Polarity_Reverser.oxz]]

==== A.D. 2025 trinkets ====
[[File:AI_Trading_Backup_Datalogger_3.oxz]]
[[File:DistantSpace.oxz]] (Meta-OXZ, downloads the [[Distant Space]] series)
[[File:Distant_Locales.oxz]] (Fills in all the other systems, not covered by Distant Realms)
[[File:Distant_Realms_US.oxz]] (See [[Distant Realms]]. Apparently they spell centre 'center')
[[File:Distant Space.oxz]] (Red backgrounds on the start screens)
[[File:Distant Thunder.oxz]] (Sound set)
[[File:Dynooverse.oxz]] ([[Dynooverse]] slowly changes the Ooniverse as you play the game)
[[File:Lost_In_Space.oxz]] ([[Lost In Space]] makes random changes to the galactic charts each time the Galactic hyperdrive is used. When you return to chart 1, it looks like chart 9 and so on)
[[File:Retro-Encabulator.oxz]] (With help from GLM-4.5)
[[File:Smart_Home_Control.oxz]] (Boil your "smart kettle" while playing Oolite)
[[File:Thargoidifier.oxz]]
[[File:Throbtastic_Crosshairs.oxz]] (Crosshairs throb while weapons are on-line)
[[File:Very_Advanced_Space_Compass.oxz]] (Turns your ship to face the ASC target)
[[File:Visits.oxz]] (System Visits Counter, an alternative to Explorers' Club)
[[File:Wildeblood_Manor.oxz]] (Puts picture backdrop on the F7 screen when G1 Vetitice is selected)
[[File:Witch_Bank.oxz]] (WIP/preview) ([[Witch Bank]] Savings Bank)
[[File:World_Builder.oxz]] ([[World Builder]] Alter the stats of a solar system)

==== A.D. 2024 trinkets ====
[[File:Demo_Screen_Backgrounds.oxz]] (setScreenBackground and setScreenBackgroundForKey JavaScript methods)
[[File:Distant_Realms.oxz]] (Updated 2025) ([[Distant Realms]] names regions on the F6 screen)
[https://bb.oolite.space/viewtopic.php?p=298353#p298353 Docked_HUDs.oxz] ([[Docked HUDs]] - originally just a minimalist docked HUD, but now brimming with information for new players)
[[File:Free_the_Slaves.oxz]] (Now secretly funding the [[Free The Slaves! NGO]])
[[File:SEX_Drive.oxz]] (It's even got a wiki page, so it must be good: [[SE-X Drive]])

==== A.D. 2015 trinkets ====
[[File:Contracted_Goods_Reminder.oxz]] (Updated 2025) (While I was away, Cholmondely made a wiki page for [[Contracted Goods Reminder]].)
[[File:Station_Self-Destruction_Codes.oxz]](While I was away, Cholmondely made a wiki page for [[Station Self-Destruction Codes]].)

==== A.D. 2014 trinkets ====
[[File:Display_Reputation.oxz]] (Updated 2025 [[Display Reputation]])
[[File:Explorers_Club_1.4.4.oxz]] (Updated 2024 [[Explorers' Club]])
[[File:Untrumbled.oxz]] (Updated 2026 [[Untrumbled]])

==== A.D. 2012 trinkets ====
[[File:Bullet_Drive_1.0.3.oxz]] (Updated 2013) (While I was away, Cholmondely made a wiki page for [[Bullet Drive]].)

== Current Interests ==
=== Album Covers ===
Check out my growing collection of OXP album covers floating to the right, '''over there ->''' 
I am unclear what purpose they'll eventually serve. But, I'm pretty sure I'm ahead of the curve with this trend, but everyone else will catch on soon.

=== A.I. Assistance ===
My current favourite AI assistants, for use with Oolite, are [https://chat.z.ai/ GLM-5.1] and [https://chat.qwen.ai/ Qwen3-Coder]. Avoid Google's Gemini, it will just waste your time.

=== Trinkets To-do ===

== A few comments ==
Wildeblood has produced some very innovative OXPs: have a good look at the now-broken [[AI Trading Assistant]], and his [[Alternative Ooniverses OXP]], [[Docked HUDs]], [[Galactic Hyperdrive OXP|Galactic Hyperdrive]], [[MilHUD 4000]], [[WEBS System‎]] & [[Wide-Screen HUD]]. His work on HUDs seems to have been very influential - many of his ideas were taken up by others, later, and most of the "modern HUDs" include several of his ideas. ''Cholmondeley 2021''

== My "How-to" OXPs ==

A collection of micro-OXPs, each demonstrating a particular Oolite javaScript technique, which might be helpful to others seeking an example to copy.

*How to use the planetary "concealment" property, introduced in Oolite 1.84:
::[[Tachyona]] is the fastest orbiting world in the co-operative. It orbits so quickly, you can see it move on the long-range chart.
*How to start (And, stop and clean up!) a timer, and how to randomize timer intervals:
::[[File:Noisy Passengers 0.1.oxz]]
*How to start (And, stop and clean up!) a frame callback while in flight:
::[[Bullet Drive]] makes the Torus Drive work somewhat more like [[classic Elite]] - no manoeuvring during flight
*How to set a station interface on the F4 screen:
::[[Station Self-Destruction Codes]] self-declared winner of the [https://bb.oolite.space/viewtopic.php?f=4&t=17178 competition] for unbalanced oxp-uber-mega-weapons
*How to change the crosshairs, without changing the whole HUD file:
::[[Crosshairs - Alerting]] shape of crosshairs depends on alert level (green/yellow/red)
*How to create the data source for a customized HUD dial:
::[[Data - Ship Name]] displays the name of your ship on your in-flight [[HUD]] (needs compatible HUD)
*How to use the player buying equipment to cause an immediate reaction (in this case, changing the HUD) unrelated to the equipment:
::[[Docked HUDs]]
*How to completely remove a worldScript which has outstayed its welcome:
::[[Untrumbled]] does not cure existing infestations but prevents future ones
*The proper way to add a new visit recording option to Explorers' Club:
::[[Serial Killer OXP]] the club will not record your visit to a system until you kill something

== My OXPs ==

In alphabetical order:
*[[File:Aaaa aaron.oxz|Aaron Aarts' Amazing Adventures]]. Some dutch guy tilts at windmills. (2024)
*[https://bb.oolite.space/viewtopic.php?f=4&t=12248 AI Combat Assistant OXP]: ''Withdrawn''
*[[AI Trading Assistant]] an autotrader - put your feet up and have a gin & tonic: '''Broke with Oolite v.1.82'''
*[[Auto Crosshairs]] crosshairs change shape when target is centred
*[[Contracted Goods Reminder]] A reminder pops up if you mistakenly sell contracted goods on the F8 market screen
*[[Crosshairs - Laser-ific]] circular dial shows laser temperature
*[[Crosshairs - Shield-tastic]] two semi-circular dials show shield levels
*[[Destination ETA]] updates the ETA - and adds a spectroscope to analyse Distant Suns
*[[Distant Locales]] retitles all F7 screen page headings with region name or co-ordinates (2025).
*[[Distant Realms]] incorporates regional titles to the F6 chart (Old Worlds/Xexedi cluster/Pulsar worlds ''etc'')
*[[Distant Suns]] moves suns further away from planets (can combine with Sensible Sun below), and changes spectroscopic qualities
*[[Dockside Services]] de-nerdifies the F4 screen
*[[Dynooverse]] - a dynamic ooniverse where the politics/economy/population of systems changes over time. (2025)
*[[Free The Slaves! NGO]] - an activist non-Galcop organization (NGO) which will nag you if you accidentally buy slaves at a Galcop station.
*[[Galactic Hyperdrive OXP|Galactic Hyperdrive]] choose your destination in the next galaxy ('''comes with 3rd chart of next galaxy''')
*[[Galaxy Names OXP|Galaxy Names]] replaces Galaxy numbers with the Acorn Archimedes Galaxy names (Santaari, Colesque ''etc'').
*[[Glare Clarifier]] cuts solar glare when close to the sun
*[https://bb.oolite.space/viewtopic.php?p=155952#p155952 HUD Vanisher] banishes the HUD in external "v"-views: [https://app.box.com/s/3nouit5vnhawea3yoz3n Download v.1.1]
*[[MilHUD 4000]] has variable brightness, de-emphasises police vessels and has a sniper-sight attached
*[[Sensible Sun]] moves suns further away from planets (can combine with Distant Suns below)
*[[Serial Killer OXP]] records systems where you killed something (a modification of the Explorer's Club OXP, 2024)
*[[Sniper Sight]]
*[[Undocumented Launch]] does this really need explaining?
*[[WEBS System‎]] defense for when your shields are down
*[[Wide-Screen HUD]] does this really need explaining?
*[[Wildeblood Manor]]: Traditional, mountain-top, fortress-yurt-dome house on Vetitice illustrated on F7 screen. (2025).
*[[World Builder]] - edit a solar system's F7 description to what you want! (2025)

=== In this vein ===
*[https://bb.oolite.space/viewtopic.php?p=174714#p174714 Template for a Galactic Hyperdrive XG] to reach more galaxies (2012). Probably only works with [[Oolite#Downloading_Earlier_versions|pre-v.1.80 versions of Oolite]]. You need to know how to manipulate the [[Galaxy Seeds]], and rejig all sorts of gubbins.

== Works in Progress (in 2015) ==

*[[Alternative Ooniverses OXP|Alternative Ooniverses]]
*[[Save and Jump OXP|Save and Jump]]
*[[OXP List (Test)]]

== List of OXPs clobbered with System 1.80's changes ==
See [https://bb.oolite.space/viewtopic.php?p=223260#p223260 here] for list, links, and a little explanation of WEBS, Alternative Ooniverse ''etc''.

== Wildeblood ==
*Exhibits a morbid fascination in the [https://bb.oolite.space/viewtopic.php?f=7&t=17793 Australian flag]
*Wildeblood removed all his OXPs from circulation as he updated them for Oolite v.1.77 (''c''. 2012). A few were updated and re-released, but not all.
*Wildeblood did not provide licenses for many of his oxp's.

== Version Archive ==
''Note that the handful of mirror sites are listed under the individual wiki pages for the relevant oxp's.''
=== AI Trading ===
*Download AI Trading Assistant 2.15.1 [[Media:Wildeblood.ai trading 2.15.1.oxz|here]], for Oolite 1.80 (downloaded {{#downloads:Wildeblood.ai trading 2.15.1.oxz}} times).
*Download AI Trading Assistant 2.15 [[Media:AI_Trading_Assistant_2.15.oxz|here]], for Oolite 1.80 (downloaded {{#downloads:AI_Trading_Assistant_2.15.oxz}} times).
*Download AI Trading Assistant 2.13.1 [[Media:AI_Trading_Assistant_2.13.1.oxz|here]], for Oolite 1.80.
*Download AI Trading Assistant 2.13 [[Media:AI_Trading_Assistant_2.13.oxz|here]], for Oolite 1.80 (downloaded {{#downloads:AI_Trading_Assistant_2.13.oxz}} times).
*Download AI Trading Assistant 2.12.4 [[Media:AI_Trading_Assistant_2.12.4.oxz|here]], for Oolite 1.80 (downloaded {{#downloads:AI_Trading_Assistant_2.12.4.oxz}} times).
*Download AI Trading Assistant 2.12.3 [[Media:AI_Trading_Assistant_2.12.3.oxz|here]], for Oolite 1.80.
*Download AI Trading Assistant 2.12.2 [[Media:AI_Trading_Assistant_2.12.2.oxz|here]], for Oolite 1.80.
*Download AI Trading Assistant 2.12.1 [[Media:AI_Trading_Assistant_2.12.1.oxz|here]], for Oolite 1.80.
*Download AI Trading Autotrade Report 0.5.3 [[Media:Autotrade_Report_Screen.oxz‎|here]], for Oolite 1.80 (downloaded {{#downloads:Autotrade_Report_Screen.oxz‎}} - 232 times).

*Download AI Trading Backup Datalogger 2.12.3 [[Media:AI_Trading_Backup_Datalogger_2.12.3.oxz|here]], for Oolite 1.80 (downloaded {{#downloads:AI_Trading_Backup_Datalogger_2.12.3.oxz}} times).
*Download AI Trading Backup Datalogger 2.12.1 [[Media:AI_Trading_Backup_Datalogger_2.12.1.oxz|here]], for Oolite 1.80.
*Download AI Trading Legality Reminder 1.0 [[Media:AI_Trading_Legality.oxz|here]], for Oolite 1.80 (downloaded {{#downloads:AI_Trading_Legality.oxz}} times).
*Download AI Trading Purchase Book 2.12 [[Media:AI_Trading_Purchase_Book_2.12.oxz|here]], for Oolite 1.80 (downloaded {{#downloads:AI_Trading_Purchase_Book_2.12.oxz}} times).
*Download AI Trading Turbotrader 1.0 [[Media:AI_Trading_Turbotrader.oxz|here]], for Oolite 1.80 (downloaded {{#downloads:AI_Trading_Turbotrader.oxz}} times).
*Download AI Trading with Yoda 1.0 [[Media:AI_Trading_with_Yoda.oxz|here]], for Oolite 1.80 (downloaded {{#downloads:AI_Trading_with_Yoda.oxz}} times).

=== Distant Space ===

Download Distant Realms [[Media:Distant_Space.oxz|here]], for Oolite 1.81 or later (downloaded {{#downloads:Distant_Space.oxz}} times).

Download Distant Suns 0.5.1 [[Media:Distant_Suns_0.5.1.oxz|here]], for Oolite 1.80 or later (downloaded {{#downloads:Distant_Suns_0.5.1.oxz}} times).

=== Explorers' Club ===

Download 1.4.4 in OXZ format [[Media:Explorers_Club_1.4.4.oxz|here]] for Oolite 1.80 or later (downloaded {{#downloads:Explorers_Club_1.4.4.oxz}} times).

Download 1.4.3 in OXZ format [[Media:Explorers_Club_1.4.3.oxz|here]] for Oolite 1.80 or later.

Download 1.4.2 in OXZ format [[Media:Explorers_Club_1.4.2.oxz|here]] for Oolite 1.80 or later.

Download 1.4.1 in OXZ format [[Media:ExplorersClub_1.4.1.oxz|here]] for Oolite 1.80 or later.

=== Animated Cross-hairs ===

Download Active Crosshairs [[Media:Active_Crosshairs.oxz|here]], for Oolite 1.80 or later (downloaded {{#downloads:Active_Crosshairs.oxz}} times).

Download Alerting Crosshairs 1.0 [[Media:Alerting Crosshairs 1.0.oxz|here]], for Oolite 1.80 or later (downloaded {{#downloads:Alerting Crosshairs 1.0.oxz}} times).

Download Auto Crosshairs 1.1.1 [[Media:AutoCrosshairs 1.1.1.oxz|here]], for Oolite 1.80 or later (downloaded {{#downloads:AutoCrosshairs 1.1.1.oxz}} times).

Download Auto Crosshairs 1.1 [[Media:AutoCrosshairs 1.1.oxz|here]], for Oolite 1.80 or later.

Download Auto Crosshairs 1.0 [[Media:AutoCrosshairs.oxz|here]], for Oolite 1.80 or later.

Download Laser-ific Crosshairs 1.3 [[Media:LaserificCrosshairs1.3.oxz|here]], for Oolite 1.80 or later (downloaded {{#downloads:LaserificCrosshairs1.3.oxz}}).

Download Laser-ific Crosshairs 1.2 [[Media:LaserificCrosshairs1.2.oxz|here]], for Oolite 1.80 or later.

Download Laser-ific Crosshairs 1.1 [[Media:LaserificCrosshairs1.1.oxz|here]], for Oolite 1.80 or later.

Download Laser-ific Crosshairs 1.0 [[Media:LaserificCrosshairs.oxz|here]], for Oolite 1.80 or later.

Download Shield-tastic Crosshairs 1.0 [[Media:ShieldtasticCrosshairs_1.0.oxz|here]], for Oolite 1.80 or later (downloaded {{#downloads:ShieldtasticCrosshairs_1.0.oxz}} times).

Download Selecto-o-matic Crosshairs 1.0.1 [[Media:Selecto-o-matic Crosshairs 1.0.1.oxz|here]], for Oolite 1.80 or later (downloaded {{#downloads:Selecto-o-matic Crosshairs 1.0.1.oxz}} times).

Download Coluber HUD Auto Crosshairs patch [[Media:Coluber CH-01 Auto Crosshairs patch.oxp.oxz|here]], (downloaded {{#downloads:Coluber CH-01 Auto Crosshairs patch.oxp.oxz}} times).

===Sensible Tweaks & Miscellaney===

Download Bullet Drive 1.0.3 [[Media:Bullet_Drive_1.0.3.oxz‎|here]], for Oolite 1.80 (downloaded {{#downloads:Bullet_Drive_1.0.3.oxz‎}} times).

Download Contracted Goods Reminder [[Media:Contracted Goods Reminder.oxz‎|here]], for Oolite 1.80 (downloaded {{#downloads:Contracted Goods Reminder.oxz‎}} times).

Download Dockside Services 1.0 [[Media:Dockside Services 1.0.oxz‎|here]], for Oolite 1.80 (downloaded {{#downloads:Dockside Services 1.0.oxz}} times).

Download Galaxy Names 1.0 [[Media:Galaxy Names 1.0.oxz‎|here]], for Oolite 1.80 (downloaded {{#downloads:Galaxy Names 1.0.oxz‎}} times).

Download Glare Clarifier [[Media:GlareClarifier.oxz‎|here]], for Oolite 1.80 (downloaded {{#downloads:GlareClarifier.oxz‎}} times).

Download Station Self-Destruction Codes [[Media:Station Self-Destruction Codes.oxz|here]], for Oolite 1.80 (downloaded {{#downloads:Station Self-Destruction Codes.oxz}} times).

Download Undocumented Launch [[Media:UndocumentedLaunch.oxz|here]], for Oolite 1.80 (downloaded {{#downloads:UndocumentedLaunch.oxz}} times).

Download Untrumbled [[Media:Untrumbled.oxz|here]], for Oolite 1.80 (downloaded {{#downloads:Untrumbled.oxz}} times).

Download Wildefire Docked HUDs 1.1 [[Media:Wildefire Docked HUDs 1.1.oxz|here]], for Oolite 1.80 (downloaded {{#downloads:Wildefire Docked HUDs 1.1.oxz}} times).

Download Wildefire Docked HUDs 1.0 [[Media:Wildefire Docked HUDs.oxz|here]], for Oolite 1.80.

=== For Oolite 1.81 ===

Download HUD Data - Ship Name [[Media:HUDDataShipName.oxz|here]], for Oolite 1.81 (downloaded {{#downloads:HUDDataShipName.oxz}} times).

Display Reputation 1.3, for Oolite 1.81 (downloaded {{#downloads:DisplayReputation1.3.oxz}} times).

[[Category:OXP authors]]

User:Wildeblood

2026-06-12T14:13:44Z

Wildeblood: /* Latest (A.D. 2026) trinkets */

[[File:Distant Space album cover.png|thumb|right|500px|Distant Space series of OXPs.]]
[[File:Thargoidifier album cover.png|thumb|right|500px|Thargoids! The Musical ([https://bb.oolite.space/viewtopic.php?p=302336#p302336 Original soundtrack album] by Thargoidifier)]]
[[File:Distant Thunder album cover.png|thumb|right|500px|Miss Sexy Voice announces goings on, and thunderous hyperspace sound.]]
[[File:Very Advanced Space Compass album cover.png|thumb|right|500px|It's the space compass, Jim, but not as we know it.]]
[[File:World Builder cover art.png|thumb|right|500px|Rule the Ooniverse your way!]]
[[File:Galactic_Hyperdrive_icon.png|thumb|right|500px|Galactic Hyperdrive programmers, because knowing where you're going...]]
[[File:Retro-Encabulator album cover.png|thumb|right|500px|You know it makes sense!]]
[[File:Distant Suns album cover.png|thumb|right|500px|The original Distant Suns OXP.]]
[[File:Trading Assistant album cover.png|thumb|right|500px|The original and genuine!]]
[[File:Distant Voyages cover art.png|thumb|right|500px|Rediscover the Galaxy]]
[[File:SE-X Drive album cover.png|thumb|right|500px|Special Equipment (Experimental)]]
[[File:Polarity_Reverser_cover_art.png|thumb|right|500px|Plasma conduits are especially reversible.]]
[[File:Distant Realms cover art.png|thumb|right|500px|Who's in charge around here?]]
[[File:Psionic Broadcaster.png|thumb|right|500px|Dynooverse Research really want to know how you feel.]]
[[File:Witch Bank.png|thumb|right|500px|More trustworthy than Westpac.]]
[[File:AristoShares_cover_art.png|thumb|right|500px|Stockbroker to the Stars]]

== Trinkets ==
==== Latest (A.D. 2026) trinkets ====
[[File:AristoShares.oxz]]
[[File:Docked_HUDs.oxz]]
[[File:Docked HUDs data sources.oxz]]
[[File:Polarity_Reverser.oxz]]

==== A.D. 2025 trinkets ====
[[File:AI_Trading_Backup_Datalogger_3.oxz]]
[[File:DistantSpace.oxz]] (Meta-OXZ, downloads the [[Distant Space]] series)
[[File:Distant_Locales.oxz]] (Fills in all the other systems, not covered by Distant Realms)
[[File:Distant_Realms_US.oxz]] (See [[Distant Realms]]. Apparently they spell centre 'center')
[[File:Distant Space.oxz]] (Red backgrounds on the start screens)
[[File:Distant Thunder.oxz]] (Sound set)
[[File:Dynooverse.oxz]] ([[Dynooverse]] slowly changes the Ooniverse as you play the game)
[[File:Lost_In_Space.oxz]] ([[Lost In Space]] makes random changes to the galactic charts each time the Galactic hyperdrive is used. When you return to chart 1, it looks like chart 9 and so on)
[[File:Retro-Encabulator.oxz]] (With help from GLM-4.5)
[[File:Smart_Home_Control.oxz]] (Boil your "smart kettle" while playing Oolite)
[[File:Thargoidifier.oxz]]
[[File:Throbtastic_Crosshairs.oxz]] (Crosshairs throb while weapons are on-line)
[[File:Very_Advanced_Space_Compass.oxz]] (Turns your ship to face the ASC target)
[[File:Visits.oxz]] (System Visits Counter, an alternative to Explorers' Club)
[[File:Wildeblood_Manor.oxz]] (Puts picture backdrop on the F7 screen when G1 Vetitice is selected)
[[File:Witch_Bank.oxz]] (WIP/preview) ([[Witch Bank]] Savings Bank)
[[File:World_Builder.oxz]] ([[World Builder]] Alter the stats of a solar system)

==== A.D. 2024 trinkets ====
[[File:Demo_Screen_Backgrounds.oxz]] (setScreenBackground and setScreenBackgroundForKey JavaScript methods)
[[File:Distant_Realms.oxz]] (Updated 2025) ([[Distant Realms]] names regions on the F6 screen)
[https://bb.oolite.space/viewtopic.php?p=298353#p298353 Docked_HUDs.oxz] ([[Docked HUDs]] - originally just a minimalist docked HUD, but now brimming with information for new players)
[[File:Free_the_Slaves.oxz]] (Now secretly funding the [[Free The Slaves! NGO]])
[[File:SEX_Drive.oxz]] (It's even got a wiki page, so it must be good: [[SE-X Drive]])

==== A.D. 2015 trinkets ====
[[File:Contracted_Goods_Reminder.oxz]] (Updated 2025) (While I was away, Cholmondely made a wiki page for [[Contracted Goods Reminder]].)
[[File:Station_Self-Destruction_Codes.oxz]](While I was away, Cholmondely made a wiki page for [[Station Self-Destruction Codes]].)

==== A.D. 2014 trinkets ====
[[File:Display_Reputation.oxz]] (Updated 2025 [[Display Reputation]])
[[File:Explorers_Club_1.4.4.oxz]] (Updated 2024 [[Explorers' Club]])
[[File:Untrumbled.oxz]] (Updated 2026 [[Untrumbled]])

==== A.D. 2012 trinkets ====
[[File:Bullet_Drive_1.0.3.oxz]] (Updated 2013) (While I was away, Cholmondely made a wiki page for [[Bullet Drive]].)

== Current Interests ==
=== Album Covers ===
Check out my growing collection of OXP album covers floating to the right, '''over there ->''' 
I am unclear what purpose they'll eventually serve. But, I'm pretty sure I'm ahead of the curve with this trend, but everyone else will catch on soon.

=== A.I. Assistance ===
My current favourite AI assistants, for use with Oolite, are [https://chat.z.ai/ GLM-5.1] and [https://chat.qwen.ai/ Qwen3-Coder]. Avoid Google's Gemini, it will just waste your time.

=== Trinkets To-do ===

== A few comments ==
Wildeblood has produced some very innovative OXPs: have a good look at the now-broken [[AI Trading Assistant]], and his [[Alternative Ooniverses OXP]], [[Docked HUDs]], [[Galactic Hyperdrive OXP|Galactic Hyperdrive]], [[MilHUD 4000]], [[WEBS System‎]] & [[Wide-Screen HUD]]. His work on HUDs seems to have been very influential - many of his ideas were taken up by others, later, and most of the "modern HUDs" include several of his ideas. ''Cholmondeley 2021''

== My "How-to" OXPs ==

A collection of micro-OXPs, each demonstrating a particular Oolite javaScript technique, which might be helpful to others seeking an example to copy.

*How to use the planetary "concealment" property, introduced in Oolite 1.84:
::[[Tachyona]] is the fastest orbiting world in the co-operative. It orbits so quickly, you can see it move on the long-range chart.
*How to start (And, stop and clean up!) a timer, and how to randomize timer intervals:
::[[File:Noisy Passengers 0.1.oxz]]
*How to start (And, stop and clean up!) a frame callback while in flight:
::[[Bullet Drive]] makes the Torus Drive work somewhat more like [[classic Elite]] - no manoeuvring during flight
*How to set a station interface on the F4 screen:
::[[Station Self-Destruction Codes]] self-declared winner of the [https://bb.oolite.space/viewtopic.php?f=4&t=17178 competition] for unbalanced oxp-uber-mega-weapons
*How to change the crosshairs, without changing the whole HUD file:
::[[Crosshairs - Alerting]] shape of crosshairs depends on alert level (green/yellow/red)
*How to create the data source for a customized HUD dial:
::[[Data - Ship Name]] displays the name of your ship on your in-flight [[HUD]] (needs compatible HUD)
*How to use the player buying equipment to cause an immediate reaction (in this case, changing the HUD) unrelated to the equipment:
::[[Docked HUDs]]
*How to completely remove a worldScript which has outstayed its welcome:
::[[Untrumbled]] does not cure existing infestations but prevents future ones
*The proper way to add a new visit recording option to Explorers' Club:
::[[Serial Killer OXP]] the club will not record your visit to a system until you kill something

== My OXPs ==

In alphabetical order:
*[[File:Aaaa aaron.oxz|Aaron Aarts' Amazing Adventures]]. Some dutch guy tilts at windmills. (2024)
*[https://bb.oolite.space/viewtopic.php?f=4&t=12248 AI Combat Assistant OXP]: ''Withdrawn''
*[[AI Trading Assistant]] an autotrader - put your feet up and have a gin & tonic: '''Broke with Oolite v.1.82'''
*[[Auto Crosshairs]] crosshairs change shape when target is centred
*[[Contracted Goods Reminder]] A reminder pops up if you mistakenly sell contracted goods on the F8 market screen
*[[Crosshairs - Laser-ific]] circular dial shows laser temperature
*[[Crosshairs - Shield-tastic]] two semi-circular dials show shield levels
*[[Destination ETA]] updates the ETA - and adds a spectroscope to analyse Distant Suns
*[[Distant Locales]] retitles all F7 screen page headings with region name or co-ordinates (2025).
*[[Distant Realms]] incorporates regional titles to the F6 chart (Old Worlds/Xexedi cluster/Pulsar worlds ''etc'')
*[[Distant Suns]] moves suns further away from planets (can combine with Sensible Sun below), and changes spectroscopic qualities
*[[Dockside Services]] de-nerdifies the F4 screen
*[[Dynooverse]] - a dynamic ooniverse where the politics/economy/population of systems changes over time. (2025)
*[[Free The Slaves! NGO]] - an activist non-Galcop organization (NGO) which will nag you if you accidentally buy slaves at a Galcop station.
*[[Galactic Hyperdrive OXP|Galactic Hyperdrive]] choose your destination in the next galaxy ('''comes with 3rd chart of next galaxy''')
*[[Galaxy Names OXP|Galaxy Names]] replaces Galaxy numbers with the Acorn Archimedes Galaxy names (Santaari, Colesque ''etc'').
*[[Glare Clarifier]] cuts solar glare when close to the sun
*[https://bb.oolite.space/viewtopic.php?p=155952#p155952 HUD Vanisher] banishes the HUD in external "v"-views: [https://app.box.com/s/3nouit5vnhawea3yoz3n Download v.1.1]
*[[MilHUD 4000]] has variable brightness, de-emphasises police vessels and has a sniper-sight attached
*[[Sensible Sun]] moves suns further away from planets (can combine with Distant Suns below)
*[[Serial Killer OXP]] records systems where you killed something (a modification of the Explorer's Club OXP, 2024)
*[[Sniper Sight]]
*[[Undocumented Launch]] does this really need explaining?
*[[WEBS System‎]] defense for when your shields are down
*[[Wide-Screen HUD]] does this really need explaining?
*[[Wildeblood Manor]]: Traditional, mountain-top, fortress-yurt-dome house on Vetitice illustrated on F7 screen. (2025).
*[[World Builder]] - edit a solar system's F7 description to what you want! (2025)

=== In this vein ===
*[https://bb.oolite.space/viewtopic.php?p=174714#p174714 Template for a Galactic Hyperdrive XG] to reach more galaxies (2012). Probably only works with [[Oolite#Downloading_Earlier_versions|pre-v.1.80 versions of Oolite]]. You need to know how to manipulate the [[Galaxy Seeds]], and rejig all sorts of gubbins.

== Works in Progress (in 2015) ==

*[[Alternative Ooniverses OXP|Alternative Ooniverses]]
*[[Save and Jump OXP|Save and Jump]]
*[[OXP List (Test)]]

== List of OXPs clobbered with System 1.80's changes ==
See [https://bb.oolite.space/viewtopic.php?p=223260#p223260 here] for list, links, and a little explanation of WEBS, Alternative Ooniverse ''etc''.

== Wildeblood ==
*Exhibits a morbid fascination in the [https://bb.oolite.space/viewtopic.php?f=7&t=17793 Australian flag]
*Wildeblood removed all his OXPs from circulation as he updated them for Oolite v.1.77 (''c''. 2012). A few were updated and re-released, but not all.
*Wildeblood did not provide licenses for many of his oxp's.

== Version Archive ==
''Note that the handful of mirror sites are listed under the individual wiki pages for the relevant oxp's.''
=== AI Trading ===
*Download AI Trading Assistant 2.15.1 [[Media:Wildeblood.ai trading 2.15.1.oxz|here]], for Oolite 1.80 (downloaded {{#downloads:Wildeblood.ai trading 2.15.1.oxz}} times).
*Download AI Trading Assistant 2.15 [[Media:AI_Trading_Assistant_2.15.oxz|here]], for Oolite 1.80 (downloaded {{#downloads:AI_Trading_Assistant_2.15.oxz}} times).
*Download AI Trading Assistant 2.13.1 [[Media:AI_Trading_Assistant_2.13.1.oxz|here]], for Oolite 1.80.
*Download AI Trading Assistant 2.13 [[Media:AI_Trading_Assistant_2.13.oxz|here]], for Oolite 1.80 (downloaded {{#downloads:AI_Trading_Assistant_2.13.oxz}} times).
*Download AI Trading Assistant 2.12.4 [[Media:AI_Trading_Assistant_2.12.4.oxz|here]], for Oolite 1.80 (downloaded {{#downloads:AI_Trading_Assistant_2.12.4.oxz}} times).
*Download AI Trading Assistant 2.12.3 [[Media:AI_Trading_Assistant_2.12.3.oxz|here]], for Oolite 1.80.
*Download AI Trading Assistant 2.12.2 [[Media:AI_Trading_Assistant_2.12.2.oxz|here]], for Oolite 1.80.
*Download AI Trading Assistant 2.12.1 [[Media:AI_Trading_Assistant_2.12.1.oxz|here]], for Oolite 1.80.
*Download AI Trading Autotrade Report 0.5.3 [[Media:Autotrade_Report_Screen.oxz‎|here]], for Oolite 1.80 (downloaded {{#downloads:Autotrade_Report_Screen.oxz‎}} - 232 times).

*Download AI Trading Backup Datalogger 2.12.3 [[Media:AI_Trading_Backup_Datalogger_2.12.3.oxz|here]], for Oolite 1.80 (downloaded {{#downloads:AI_Trading_Backup_Datalogger_2.12.3.oxz}} times).
*Download AI Trading Backup Datalogger 2.12.1 [[Media:AI_Trading_Backup_Datalogger_2.12.1.oxz|here]], for Oolite 1.80.
*Download AI Trading Legality Reminder 1.0 [[Media:AI_Trading_Legality.oxz|here]], for Oolite 1.80 (downloaded {{#downloads:AI_Trading_Legality.oxz}} times).
*Download AI Trading Purchase Book 2.12 [[Media:AI_Trading_Purchase_Book_2.12.oxz|here]], for Oolite 1.80 (downloaded {{#downloads:AI_Trading_Purchase_Book_2.12.oxz}} times).
*Download AI Trading Turbotrader 1.0 [[Media:AI_Trading_Turbotrader.oxz|here]], for Oolite 1.80 (downloaded {{#downloads:AI_Trading_Turbotrader.oxz}} times).
*Download AI Trading with Yoda 1.0 [[Media:AI_Trading_with_Yoda.oxz|here]], for Oolite 1.80 (downloaded {{#downloads:AI_Trading_with_Yoda.oxz}} times).

=== Distant Space ===

Download Distant Realms [[Media:Distant_Space.oxz|here]], for Oolite 1.81 or later (downloaded {{#downloads:Distant_Space.oxz}} times).

Download Distant Suns 0.5.1 [[Media:Distant_Suns_0.5.1.oxz|here]], for Oolite 1.80 or later (downloaded {{#downloads:Distant_Suns_0.5.1.oxz}} times).

=== Explorers' Club ===

Download 1.4.4 in OXZ format [[Media:Explorers_Club_1.4.4.oxz|here]] for Oolite 1.80 or later (downloaded {{#downloads:Explorers_Club_1.4.4.oxz}} times).

Download 1.4.3 in OXZ format [[Media:Explorers_Club_1.4.3.oxz|here]] for Oolite 1.80 or later.

Download 1.4.2 in OXZ format [[Media:Explorers_Club_1.4.2.oxz|here]] for Oolite 1.80 or later.

Download 1.4.1 in OXZ format [[Media:ExplorersClub_1.4.1.oxz|here]] for Oolite 1.80 or later.

=== Animated Cross-hairs ===

Download Active Crosshairs [[Media:Active_Crosshairs.oxz|here]], for Oolite 1.80 or later (downloaded {{#downloads:Active_Crosshairs.oxz}} times).

Download Alerting Crosshairs 1.0 [[Media:Alerting Crosshairs 1.0.oxz|here]], for Oolite 1.80 or later (downloaded {{#downloads:Alerting Crosshairs 1.0.oxz}} times).

Download Auto Crosshairs 1.1.1 [[Media:AutoCrosshairs 1.1.1.oxz|here]], for Oolite 1.80 or later (downloaded {{#downloads:AutoCrosshairs 1.1.1.oxz}} times).

Download Auto Crosshairs 1.1 [[Media:AutoCrosshairs 1.1.oxz|here]], for Oolite 1.80 or later.

Download Auto Crosshairs 1.0 [[Media:AutoCrosshairs.oxz|here]], for Oolite 1.80 or later.

Download Laser-ific Crosshairs 1.3 [[Media:LaserificCrosshairs1.3.oxz|here]], for Oolite 1.80 or later (downloaded {{#downloads:LaserificCrosshairs1.3.oxz}}).

Download Laser-ific Crosshairs 1.2 [[Media:LaserificCrosshairs1.2.oxz|here]], for Oolite 1.80 or later.

Download Laser-ific Crosshairs 1.1 [[Media:LaserificCrosshairs1.1.oxz|here]], for Oolite 1.80 or later.

Download Laser-ific Crosshairs 1.0 [[Media:LaserificCrosshairs.oxz|here]], for Oolite 1.80 or later.

Download Shield-tastic Crosshairs 1.0 [[Media:ShieldtasticCrosshairs_1.0.oxz|here]], for Oolite 1.80 or later (downloaded {{#downloads:ShieldtasticCrosshairs_1.0.oxz}} times).

Download Selecto-o-matic Crosshairs 1.0.1 [[Media:Selecto-o-matic Crosshairs 1.0.1.oxz|here]], for Oolite 1.80 or later (downloaded {{#downloads:Selecto-o-matic Crosshairs 1.0.1.oxz}} times).

Download Coluber HUD Auto Crosshairs patch [[Media:Coluber CH-01 Auto Crosshairs patch.oxp.oxz|here]], (downloaded {{#downloads:Coluber CH-01 Auto Crosshairs patch.oxp.oxz}} times).

===Sensible Tweaks & Miscellaney===

Download Bullet Drive 1.0.3 [[Media:Bullet_Drive_1.0.3.oxz‎|here]], for Oolite 1.80 (downloaded {{#downloads:Bullet_Drive_1.0.3.oxz‎}} times).

Download Contracted Goods Reminder [[Media:Contracted Goods Reminder.oxz‎|here]], for Oolite 1.80 (downloaded {{#downloads:Contracted Goods Reminder.oxz‎}} times).

Download Dockside Services 1.0 [[Media:Dockside Services 1.0.oxz‎|here]], for Oolite 1.80 (downloaded {{#downloads:Dockside Services 1.0.oxz}} times).

Download Galaxy Names 1.0 [[Media:Galaxy Names 1.0.oxz‎|here]], for Oolite 1.80 (downloaded {{#downloads:Galaxy Names 1.0.oxz‎}} times).

Download Glare Clarifier [[Media:GlareClarifier.oxz‎|here]], for Oolite 1.80 (downloaded {{#downloads:GlareClarifier.oxz‎}} times).

Download Station Self-Destruction Codes [[Media:Station Self-Destruction Codes.oxz|here]], for Oolite 1.80 (downloaded {{#downloads:Station Self-Destruction Codes.oxz}} times).

Download Undocumented Launch [[Media:UndocumentedLaunch.oxz|here]], for Oolite 1.80 (downloaded {{#downloads:UndocumentedLaunch.oxz}} times).

Download Untrumbled [[Media:Untrumbled.oxz|here]], for Oolite 1.80 (downloaded {{#downloads:Untrumbled.oxz}} times).

Download Wildefire Docked HUDs 1.1 [[Media:Wildefire Docked HUDs 1.1.oxz|here]], for Oolite 1.80 (downloaded {{#downloads:Wildefire Docked HUDs 1.1.oxz}} times).

Download Wildefire Docked HUDs 1.0 [[Media:Wildefire Docked HUDs.oxz|here]], for Oolite 1.80.

=== For Oolite 1.81 ===

Download HUD Data - Ship Name [[Media:HUDDataShipName.oxz|here]], for Oolite 1.81 (downloaded {{#downloads:HUDDataShipName.oxz}} times).

Display Reputation 1.3, for Oolite 1.81 (downloaded {{#downloads:DisplayReputation1.3.oxz}} times).

[[Category:OXP authors]]

File:Docked HUDs data sources.oxz

2026-06-12T14:05:43Z

Wildeblood: /* Summary */ Hey!

== Summary ==
Version 1.5

This is the script that provides the function labels for Docked HUDs. If you have Docked HUDs, version 1.4, you can delete the file Scripts/docked_huds_button_data.js from within it, and this OXZ will take over.

Here is an actual manifest of the contents of this OXZ.
There are no "strings" of text whatsoever in the javascript.
If you wish to change the words that appear,
edit the configuration file, "descriptions.plist".
<pre>
Docked_HUDs_data_sources.oxz/
├── manifest.plist
├── README.txt
├── Backup/
│ └── descriptions.plist.txt
├── Config/
│ ├── descriptions.plist
│ └── world-scripts.plist
└── Scripts/
└── docked_huds_button_data.js
</pre>

File:Docked HUDs data sources.oxz

2026-06-12T13:39:18Z

Wildeblood: Version 1.5

== Summary ==
Version 1.5

File:Untrumbled.oxz

2026-06-11T08:52:57Z

Wildeblood: Wildeblood uploaded a new version of File:Untrumbled.oxz

User:Wildeblood

2026-06-11T08:01:35Z

Wildeblood: /* A.D. 2014 trinkets */

[[File:Distant Space album cover.png|thumb|right|500px|Distant Space series of OXPs.]]
[[File:Thargoidifier album cover.png|thumb|right|500px|Thargoids! The Musical ([https://bb.oolite.space/viewtopic.php?p=302336#p302336 Original soundtrack album] by Thargoidifier)]]
[[File:Distant Thunder album cover.png|thumb|right|500px|Miss Sexy Voice announces goings on, and thunderous hyperspace sound.]]
[[File:Very Advanced Space Compass album cover.png|thumb|right|500px|It's the space compass, Jim, but not as we know it.]]
[[File:World Builder cover art.png|thumb|right|500px|Rule the Ooniverse your way!]]
[[File:Galactic_Hyperdrive_icon.png|thumb|right|500px|Galactic Hyperdrive programmers, because knowing where you're going...]]
[[File:Retro-Encabulator album cover.png|thumb|right|500px|You know it makes sense!]]
[[File:Distant Suns album cover.png|thumb|right|500px|The original Distant Suns OXP.]]
[[File:Trading Assistant album cover.png|thumb|right|500px|The original and genuine!]]
[[File:Distant Voyages cover art.png|thumb|right|500px|Rediscover the Galaxy]]
[[File:SE-X Drive album cover.png|thumb|right|500px|Special Equipment (Experimental)]]
[[File:Polarity_Reverser_cover_art.png|thumb|right|500px|Plasma conduits are especially reversible.]]
[[File:Distant Realms cover art.png|thumb|right|500px|Who's in charge around here?]]
[[File:Psionic Broadcaster.png|thumb|right|500px|Dynooverse Research really want to know how you feel.]]
[[File:Witch Bank.png|thumb|right|500px|More trustworthy than Westpac.]]
[[File:AristoShares_cover_art.png|thumb|right|500px|Stockbroker to the Stars]]

== Trinkets ==
==== Latest (A.D. 2026) trinkets ====
[[File:AristoShares.oxz]]
[[File:Docked_HUDs.oxz]]
[[File:Polarity_Reverser.oxz]]

==== A.D. 2025 trinkets ====
[[File:AI_Trading_Backup_Datalogger_3.oxz]]
[[File:DistantSpace.oxz]] (Meta-OXZ, downloads the [[Distant Space]] series)
[[File:Distant_Locales.oxz]] (Fills in all the other systems, not covered by Distant Realms)
[[File:Distant_Realms_US.oxz]] (See [[Distant Realms]]. Apparently they spell centre 'center')
[[File:Distant Space.oxz]] (Red backgrounds on the start screens)
[[File:Distant Thunder.oxz]] (Sound set)
[[File:Dynooverse.oxz]] ([[Dynooverse]] slowly changes the Ooniverse as you play the game)
[[File:Lost_In_Space.oxz]] ([[Lost In Space]] makes random changes to the galactic charts each time the Galactic hyperdrive is used. When you return to chart 1, it looks like chart 9 and so on)
[[File:Retro-Encabulator.oxz]] (With help from GLM-4.5)
[[File:Smart_Home_Control.oxz]] (Boil your "smart kettle" while playing Oolite)
[[File:Thargoidifier.oxz]]
[[File:Throbtastic_Crosshairs.oxz]] (Crosshairs throb while weapons are on-line)
[[File:Very_Advanced_Space_Compass.oxz]] (Turns your ship to face the ASC target)
[[File:Visits.oxz]] (System Visits Counter, an alternative to Explorers' Club)
[[File:Wildeblood_Manor.oxz]] (Puts picture backdrop on the F7 screen when G1 Vetitice is selected)
[[File:Witch_Bank.oxz]] (WIP/preview) ([[Witch Bank]] Savings Bank)
[[File:World_Builder.oxz]] ([[World Builder]] Alter the stats of a solar system)

==== A.D. 2024 trinkets ====
[[File:Demo_Screen_Backgrounds.oxz]] (setScreenBackground and setScreenBackgroundForKey JavaScript methods)
[[File:Distant_Realms.oxz]] (Updated 2025) ([[Distant Realms]] names regions on the F6 screen)
[https://bb.oolite.space/viewtopic.php?p=298353#p298353 Docked_HUDs.oxz] ([[Docked HUDs]] - originally just a minimalist docked HUD, but now brimming with information for new players)
[[File:Free_the_Slaves.oxz]] (Now secretly funding the [[Free The Slaves! NGO]])
[[File:SEX_Drive.oxz]] (It's even got a wiki page, so it must be good: [[SE-X Drive]])

==== A.D. 2015 trinkets ====
[[File:Contracted_Goods_Reminder.oxz]] (Updated 2025) (While I was away, Cholmondely made a wiki page for [[Contracted Goods Reminder]].)
[[File:Station_Self-Destruction_Codes.oxz]](While I was away, Cholmondely made a wiki page for [[Station Self-Destruction Codes]].)

==== A.D. 2014 trinkets ====
[[File:Display_Reputation.oxz]] (Updated 2025 [[Display Reputation]])
[[File:Explorers_Club_1.4.4.oxz]] (Updated 2024 [[Explorers' Club]])
[[File:Untrumbled.oxz]] (Updated 2026 [[Untrumbled]])

==== A.D. 2012 trinkets ====
[[File:Bullet_Drive_1.0.3.oxz]] (Updated 2013) (While I was away, Cholmondely made a wiki page for [[Bullet Drive]].)

== Current Interests ==
=== Album Covers ===
Check out my growing collection of OXP album covers floating to the right, '''over there ->''' 
I am unclear what purpose they'll eventually serve. But, I'm pretty sure I'm ahead of the curve with this trend, but everyone else will catch on soon.

=== A.I. Assistance ===
My current favourite AI assistants, for use with Oolite, are [https://chat.z.ai/ GLM-5.1] and [https://chat.qwen.ai/ Qwen3-Coder]. Avoid Google's Gemini, it will just waste your time.

=== Trinkets To-do ===

== A few comments ==
Wildeblood has produced some very innovative OXPs: have a good look at the now-broken [[AI Trading Assistant]], and his [[Alternative Ooniverses OXP]], [[Docked HUDs]], [[Galactic Hyperdrive OXP|Galactic Hyperdrive]], [[MilHUD 4000]], [[WEBS System‎]] & [[Wide-Screen HUD]]. His work on HUDs seems to have been very influential - many of his ideas were taken up by others, later, and most of the "modern HUDs" include several of his ideas. ''Cholmondeley 2021''

== My "How-to" OXPs ==

A collection of micro-OXPs, each demonstrating a particular Oolite javaScript technique, which might be helpful to others seeking an example to copy.

*How to use the planetary "concealment" property, introduced in Oolite 1.84:
::[[Tachyona]] is the fastest orbiting world in the co-operative. It orbits so quickly, you can see it move on the long-range chart.
*How to start (And, stop and clean up!) a timer, and how to randomize timer intervals:
::[[File:Noisy Passengers 0.1.oxz]]
*How to start (And, stop and clean up!) a frame callback while in flight:
::[[Bullet Drive]] makes the Torus Drive work somewhat more like [[classic Elite]] - no manoeuvring during flight
*How to set a station interface on the F4 screen:
::[[Station Self-Destruction Codes]] self-declared winner of the [https://bb.oolite.space/viewtopic.php?f=4&t=17178 competition] for unbalanced oxp-uber-mega-weapons
*How to change the crosshairs, without changing the whole HUD file:
::[[Crosshairs - Alerting]] shape of crosshairs depends on alert level (green/yellow/red)
*How to create the data source for a customized HUD dial:
::[[Data - Ship Name]] displays the name of your ship on your in-flight [[HUD]] (needs compatible HUD)
*How to use the player buying equipment to cause an immediate reaction (in this case, changing the HUD) unrelated to the equipment:
::[[Docked HUDs]]
*How to completely remove a worldScript which has outstayed its welcome:
::[[Untrumbled]] does not cure existing infestations but prevents future ones
*The proper way to add a new visit recording option to Explorers' Club:
::[[Serial Killer OXP]] the club will not record your visit to a system until you kill something

== My OXPs ==

In alphabetical order:
*[[File:Aaaa aaron.oxz|Aaron Aarts' Amazing Adventures]]. Some dutch guy tilts at windmills. (2024)
*[https://bb.oolite.space/viewtopic.php?f=4&t=12248 AI Combat Assistant OXP]: ''Withdrawn''
*[[AI Trading Assistant]] an autotrader - put your feet up and have a gin & tonic: '''Broke with Oolite v.1.82'''
*[[Auto Crosshairs]] crosshairs change shape when target is centred
*[[Contracted Goods Reminder]] A reminder pops up if you mistakenly sell contracted goods on the F8 market screen
*[[Crosshairs - Laser-ific]] circular dial shows laser temperature
*[[Crosshairs - Shield-tastic]] two semi-circular dials show shield levels
*[[Destination ETA]] updates the ETA - and adds a spectroscope to analyse Distant Suns
*[[Distant Locales]] retitles all F7 screen page headings with region name or co-ordinates (2025).
*[[Distant Realms]] incorporates regional titles to the F6 chart (Old Worlds/Xexedi cluster/Pulsar worlds ''etc'')
*[[Distant Suns]] moves suns further away from planets (can combine with Sensible Sun below), and changes spectroscopic qualities
*[[Dockside Services]] de-nerdifies the F4 screen
*[[Dynooverse]] - a dynamic ooniverse where the politics/economy/population of systems changes over time. (2025)
*[[Free The Slaves! NGO]] - an activist non-Galcop organization (NGO) which will nag you if you accidentally buy slaves at a Galcop station.
*[[Galactic Hyperdrive OXP|Galactic Hyperdrive]] choose your destination in the next galaxy ('''comes with 3rd chart of next galaxy''')
*[[Galaxy Names OXP|Galaxy Names]] replaces Galaxy numbers with the Acorn Archimedes Galaxy names (Santaari, Colesque ''etc'').
*[[Glare Clarifier]] cuts solar glare when close to the sun
*[https://bb.oolite.space/viewtopic.php?p=155952#p155952 HUD Vanisher] banishes the HUD in external "v"-views: [https://app.box.com/s/3nouit5vnhawea3yoz3n Download v.1.1]
*[[MilHUD 4000]] has variable brightness, de-emphasises police vessels and has a sniper-sight attached
*[[Sensible Sun]] moves suns further away from planets (can combine with Distant Suns below)
*[[Serial Killer OXP]] records systems where you killed something (a modification of the Explorer's Club OXP, 2024)
*[[Sniper Sight]]
*[[Undocumented Launch]] does this really need explaining?
*[[WEBS System‎]] defense for when your shields are down
*[[Wide-Screen HUD]] does this really need explaining?
*[[Wildeblood Manor]]: Traditional, mountain-top, fortress-yurt-dome house on Vetitice illustrated on F7 screen. (2025).
*[[World Builder]] - edit a solar system's F7 description to what you want! (2025)

=== In this vein ===
*[https://bb.oolite.space/viewtopic.php?p=174714#p174714 Template for a Galactic Hyperdrive XG] to reach more galaxies (2012). Probably only works with [[Oolite#Downloading_Earlier_versions|pre-v.1.80 versions of Oolite]]. You need to know how to manipulate the [[Galaxy Seeds]], and rejig all sorts of gubbins.

== Works in Progress (in 2015) ==

*[[Alternative Ooniverses OXP|Alternative Ooniverses]]
*[[Save and Jump OXP|Save and Jump]]
*[[OXP List (Test)]]

== List of OXPs clobbered with System 1.80's changes ==
See [https://bb.oolite.space/viewtopic.php?p=223260#p223260 here] for list, links, and a little explanation of WEBS, Alternative Ooniverse ''etc''.

== Wildeblood ==
*Exhibits a morbid fascination in the [https://bb.oolite.space/viewtopic.php?f=7&t=17793 Australian flag]
*Wildeblood removed all his OXPs from circulation as he updated them for Oolite v.1.77 (''c''. 2012). A few were updated and re-released, but not all.
*Wildeblood did not provide licenses for many of his oxp's.

== Version Archive ==
''Note that the handful of mirror sites are listed under the individual wiki pages for the relevant oxp's.''
=== AI Trading ===
*Download AI Trading Assistant 2.15.1 [[Media:Wildeblood.ai trading 2.15.1.oxz|here]], for Oolite 1.80 (downloaded {{#downloads:Wildeblood.ai trading 2.15.1.oxz}} times).
*Download AI Trading Assistant 2.15 [[Media:AI_Trading_Assistant_2.15.oxz|here]], for Oolite 1.80 (downloaded {{#downloads:AI_Trading_Assistant_2.15.oxz}} times).
*Download AI Trading Assistant 2.13.1 [[Media:AI_Trading_Assistant_2.13.1.oxz|here]], for Oolite 1.80.
*Download AI Trading Assistant 2.13 [[Media:AI_Trading_Assistant_2.13.oxz|here]], for Oolite 1.80 (downloaded {{#downloads:AI_Trading_Assistant_2.13.oxz}} times).
*Download AI Trading Assistant 2.12.4 [[Media:AI_Trading_Assistant_2.12.4.oxz|here]], for Oolite 1.80 (downloaded {{#downloads:AI_Trading_Assistant_2.12.4.oxz}} times).
*Download AI Trading Assistant 2.12.3 [[Media:AI_Trading_Assistant_2.12.3.oxz|here]], for Oolite 1.80.
*Download AI Trading Assistant 2.12.2 [[Media:AI_Trading_Assistant_2.12.2.oxz|here]], for Oolite 1.80.
*Download AI Trading Assistant 2.12.1 [[Media:AI_Trading_Assistant_2.12.1.oxz|here]], for Oolite 1.80.
*Download AI Trading Autotrade Report 0.5.3 [[Media:Autotrade_Report_Screen.oxz‎|here]], for Oolite 1.80 (downloaded {{#downloads:Autotrade_Report_Screen.oxz‎}} - 232 times).

*Download AI Trading Backup Datalogger 2.12.3 [[Media:AI_Trading_Backup_Datalogger_2.12.3.oxz|here]], for Oolite 1.80 (downloaded {{#downloads:AI_Trading_Backup_Datalogger_2.12.3.oxz}} times).
*Download AI Trading Backup Datalogger 2.12.1 [[Media:AI_Trading_Backup_Datalogger_2.12.1.oxz|here]], for Oolite 1.80.
*Download AI Trading Legality Reminder 1.0 [[Media:AI_Trading_Legality.oxz|here]], for Oolite 1.80 (downloaded {{#downloads:AI_Trading_Legality.oxz}} times).
*Download AI Trading Purchase Book 2.12 [[Media:AI_Trading_Purchase_Book_2.12.oxz|here]], for Oolite 1.80 (downloaded {{#downloads:AI_Trading_Purchase_Book_2.12.oxz}} times).
*Download AI Trading Turbotrader 1.0 [[Media:AI_Trading_Turbotrader.oxz|here]], for Oolite 1.80 (downloaded {{#downloads:AI_Trading_Turbotrader.oxz}} times).
*Download AI Trading with Yoda 1.0 [[Media:AI_Trading_with_Yoda.oxz|here]], for Oolite 1.80 (downloaded {{#downloads:AI_Trading_with_Yoda.oxz}} times).

=== Distant Space ===

Download Distant Realms [[Media:Distant_Space.oxz|here]], for Oolite 1.81 or later (downloaded {{#downloads:Distant_Space.oxz}} times).

Download Distant Suns 0.5.1 [[Media:Distant_Suns_0.5.1.oxz|here]], for Oolite 1.80 or later (downloaded {{#downloads:Distant_Suns_0.5.1.oxz}} times).

=== Explorers' Club ===

Download 1.4.4 in OXZ format [[Media:Explorers_Club_1.4.4.oxz|here]] for Oolite 1.80 or later (downloaded {{#downloads:Explorers_Club_1.4.4.oxz}} times).

Download 1.4.3 in OXZ format [[Media:Explorers_Club_1.4.3.oxz|here]] for Oolite 1.80 or later.

Download 1.4.2 in OXZ format [[Media:Explorers_Club_1.4.2.oxz|here]] for Oolite 1.80 or later.

Download 1.4.1 in OXZ format [[Media:ExplorersClub_1.4.1.oxz|here]] for Oolite 1.80 or later.

=== Animated Cross-hairs ===

Download Active Crosshairs [[Media:Active_Crosshairs.oxz|here]], for Oolite 1.80 or later (downloaded {{#downloads:Active_Crosshairs.oxz}} times).

Download Alerting Crosshairs 1.0 [[Media:Alerting Crosshairs 1.0.oxz|here]], for Oolite 1.80 or later (downloaded {{#downloads:Alerting Crosshairs 1.0.oxz}} times).

Download Auto Crosshairs 1.1.1 [[Media:AutoCrosshairs 1.1.1.oxz|here]], for Oolite 1.80 or later (downloaded {{#downloads:AutoCrosshairs 1.1.1.oxz}} times).

Download Auto Crosshairs 1.1 [[Media:AutoCrosshairs 1.1.oxz|here]], for Oolite 1.80 or later.

Download Auto Crosshairs 1.0 [[Media:AutoCrosshairs.oxz|here]], for Oolite 1.80 or later.

Download Laser-ific Crosshairs 1.3 [[Media:LaserificCrosshairs1.3.oxz|here]], for Oolite 1.80 or later (downloaded {{#downloads:LaserificCrosshairs1.3.oxz}}).

Download Laser-ific Crosshairs 1.2 [[Media:LaserificCrosshairs1.2.oxz|here]], for Oolite 1.80 or later.

Download Laser-ific Crosshairs 1.1 [[Media:LaserificCrosshairs1.1.oxz|here]], for Oolite 1.80 or later.

Download Laser-ific Crosshairs 1.0 [[Media:LaserificCrosshairs.oxz|here]], for Oolite 1.80 or later.

Download Shield-tastic Crosshairs 1.0 [[Media:ShieldtasticCrosshairs_1.0.oxz|here]], for Oolite 1.80 or later (downloaded {{#downloads:ShieldtasticCrosshairs_1.0.oxz}} times).

Download Selecto-o-matic Crosshairs 1.0.1 [[Media:Selecto-o-matic Crosshairs 1.0.1.oxz|here]], for Oolite 1.80 or later (downloaded {{#downloads:Selecto-o-matic Crosshairs 1.0.1.oxz}} times).

Download Coluber HUD Auto Crosshairs patch [[Media:Coluber CH-01 Auto Crosshairs patch.oxp.oxz|here]], (downloaded {{#downloads:Coluber CH-01 Auto Crosshairs patch.oxp.oxz}} times).

===Sensible Tweaks & Miscellaney===

Download Bullet Drive 1.0.3 [[Media:Bullet_Drive_1.0.3.oxz‎|here]], for Oolite 1.80 (downloaded {{#downloads:Bullet_Drive_1.0.3.oxz‎}} times).

Download Contracted Goods Reminder [[Media:Contracted Goods Reminder.oxz‎|here]], for Oolite 1.80 (downloaded {{#downloads:Contracted Goods Reminder.oxz‎}} times).

Download Dockside Services 1.0 [[Media:Dockside Services 1.0.oxz‎|here]], for Oolite 1.80 (downloaded {{#downloads:Dockside Services 1.0.oxz}} times).

Download Galaxy Names 1.0 [[Media:Galaxy Names 1.0.oxz‎|here]], for Oolite 1.80 (downloaded {{#downloads:Galaxy Names 1.0.oxz‎}} times).

Download Glare Clarifier [[Media:GlareClarifier.oxz‎|here]], for Oolite 1.80 (downloaded {{#downloads:GlareClarifier.oxz‎}} times).

Download Station Self-Destruction Codes [[Media:Station Self-Destruction Codes.oxz|here]], for Oolite 1.80 (downloaded {{#downloads:Station Self-Destruction Codes.oxz}} times).

Download Undocumented Launch [[Media:UndocumentedLaunch.oxz|here]], for Oolite 1.80 (downloaded {{#downloads:UndocumentedLaunch.oxz}} times).

Download Untrumbled [[Media:Untrumbled.oxz|here]], for Oolite 1.80 (downloaded {{#downloads:Untrumbled.oxz}} times).

Download Wildefire Docked HUDs 1.1 [[Media:Wildefire Docked HUDs 1.1.oxz|here]], for Oolite 1.80 (downloaded {{#downloads:Wildefire Docked HUDs 1.1.oxz}} times).

Download Wildefire Docked HUDs 1.0 [[Media:Wildefire Docked HUDs.oxz|here]], for Oolite 1.80.

=== For Oolite 1.81 ===

Download HUD Data - Ship Name [[Media:HUDDataShipName.oxz|here]], for Oolite 1.81 (downloaded {{#downloads:HUDDataShipName.oxz}} times).

Display Reputation 1.3, for Oolite 1.81 (downloaded {{#downloads:DisplayReputation1.3.oxz}} times).

[[Category:OXP authors]]

File:Untrumbled.oxz

2026-06-11T07:45:17Z

Wildeblood: Wildeblood uploaded a new version of File:Untrumbled.oxz