Relationships of goods and global pricing
==================================

Ok we've installed the DLL and the addon in general in the last post. This post will introduce you to the first INI file in the mod: The good_relations.ini. The file provides information about goods in general and their relationships, controls the global pricing and the revenue bases gain when selling the good.

So here is the structure of a single entry in the good_relations.ini:

[Good
nickname = commodity_nickname
revenue = factor
depends = [commodity_nickname, count[, commodity_nickname, count
function = [see below

At first glance its simple, so here we go into the details:

nickname
-----------

The nickname as it appears in Goods.ini or one of the other INI files.


revenue
---------

The revenue controls a factor, which is added to the price of a good to account
for production cost, storage costs and to give the base a benefit for trading. This will be used in another stage of this mod, you can guess for what.


depends
----------

One of the things missing in the original game is the relationships between goods. My favorite example is ship hull panels, which describes a set of other goods as we know from the goods description in the game:

[Good
nickname=commodity_ship_hull_panels
depends=commodity_boron,2,commodity_basic_alloys,5,commodity_super_alloys,5,commodity_polymers,3,commodity_hydrocarbons,3

This says that ship hull panels require:

- 2 items boron
- 5 items basic alloys
- 5 items super alloys
- 3 items polymers
- 3 items hydrocarbons

Now the addon knows what is required for ship hull panels, but how does it use this information?

A. For production:

With this addon bases will actually produce stuff. But to be able to produce an item a factory requires materials - the depends line tells the addon that 1 ship hull panel can only be produced if the demand for 2 items boron, 5 items basic alloys, 5 items super alloys, 3 items polymers and 3 items hydrocarbons has been met. Only if this demand has been met you'll see at some point later in time one ship hull panel appear for sale at the commodity trader.

B. For price calculation:

Since we know the price of all dependencies, we know the revenue value we can calculate the sale price of the ship hull panel using the following formula:

price=(2*boron_price+5*basic_alloy_price+5*super_alloy_price+3*polymer_price+3*hydrocarbons_price)*(1.0+revenue)

This type of price calculation only applies for goods, which have dependencies. E.g. water and oxygen use a different algorithm. Additionally this is a global price value and is basically the same for all bases or stations. The prices used in the calculation itself (e.g. boron_price) are the demand prices of boron at the producing station itself.


function
----------

We just saw the calculation scheme for global prices for goods, which have a dependency. But there are also goods, which don't have a dependency: Water or oxygen for example.

The prices for these goods is calculated using a mathematical function. The addon provides a set of functions to choose from:

- Constant
- Periodic (aka sine wave)
- Linear (Linear rise or drop)
- Slope (Logarithmic rise or drop)
- Random fluctuation

These functions allow you to simulate market conditions for each and every good on the market individually. A simulation of H-Fuel for example could be specified like the following:

[Good
nickname = commodity_H_fuel
revenue = 0.05 ; 5% revenue
function = linear, 300, 10, 100

This function line for H-Fuel causes its price to linearly decline over 100 (game-)days from a starting price of 300 to its all time low of 10 credits. This could be
the case if all new built ships were using MOX instead of H-Fuel and thus the global demand of H-Fuel were declining.

Examples for other functions:

function = constant, price
function = constant, 15

This line causes the price for a good to remain fixed at 15 credits.


function = periodic, median-price, amplitude, game-days
function = periodic, 300, 20, 2

This causes the price of a good to follow along a sine wave from 280 to 320, which starts at 300. A period of the sine wave (e.g. 300 to 320 to 300 to 280 to 300) takes 2 (game-)days.


function = slope, start-price, end-price, game-days
function = slope, 300, 10, 100

This causes the price of a good to fall from 300 credits to 10 credits via a logarithmic curve over 100 (game-)days. A rise can be implemented by specifying
a higher value than 300 in replacement of the 10.


function = linear, start-price, end-price, game-days
function = linear, 300, 10, 100

See above.

function = randfluct, average-price, fluct
function = randfluct, 300, 0.05

This causes the price to randomly fluctuate around the average of 300 by as much as 5 per cent.


A full entry would look like this:

[Good
nickname = commodity_ship_hull_panels
depends = commodity_boron,2,commodity_basic_alloys,5,commodity_super_alloys,5,commodity_polymers,3,commodity_hydrocarbons,3
revenue = 0.05

or

[Good
nickname = commodity_boron
revenue = 0.01
function = periodic, 120, 20, 5

This global price calculation is used for bases, which do not have a specific price calculation specified for them in markets.ini. The capabilities in that file builds on the contents of this file - To start to use this in your mod, I would suggest writing the good_relations.ini file first.

The markets.ini will be described in the next post in a couple of days.


Edited by - grover on 1/20/2006 1:18:13 AM

Edited by - grover on 1/25/2006 12:52:12 AM

markets.ini
==========

In the previous post we've seen the global price building scheme, which is basically used for all bases which aren't configured to have demand, supply, production or sales. In this post we'll talk about a new file, which specifies these details. It builds upon good_relations.ini, thus the other INI is required. This is the most complex INI file used by the mod, so free your mind before reading this.

One more note: I've added a new function description to the previous post. That function should be really useful for this file, as we'll use lots of functions here. I promise.

Ok, here is an example entry for markets.ini:

New markets.ini structure:

[Market
base = nickname
newsticker = ids,category,ids,category,ids,category
stock=nickname,initial,max,pfactor-low,pfactor-high
production=nickname,function*,waste,waste-amount,waste,waste-amount
supply=nickname,day_factor,function*
demand=nickname,function*
sale=nickname,function*
reputation=nickname,factor,influence

Oh my, whats all of this. Lets see:

base
-----

The nickname of the base.


news_ticker
--------------

This controls the structure of the news ticker for the base, its structure is the following:

news_ticker=[ids,category[,ids,category,...

Basically it tells fleconomy.dll which good categories (commodities, equipment, ships, ammo) to display in the news ticker and which prefix to use for them. So its structure could be this one:

news_ticker=1163,500,1164,10,1165,1

This would result in the display of Commodity Trader followed by all commodities, then Equipment Trader followed by all equipment and finally Ship Trader followed by all ships. You can include other stuff like ammo by including it in this line. (The category of a good is the 4th column in its MarketGood entry in one of the INI-files in data\equipment.) You could also display munition prices and others this way.


stock
------

This controls the stock of a single good maintained by the dealer.

stock=A,B,C,D,E

Where:

A=String: Nickname of the good
B=Integer: Initial stock for new games
C=Integer: Maximum number of items in stock
D=Float: Price factor low. Determines the multiplier to the global price if the stock is low.
E=Float: Price factor high. Determines the multiplier to the global price if the stock is high.

Using this setting we control how many items of a good the trader will accumulate before refusing to buy it from the player (or an NPC.) The stock also controls the pricing of a good. Usually the price for goods with a lot of stock is lower than for rare goods. The price-low factor and price-high factor are multipliers to the current global price to calculate the good price. The price of a good can't drop below 1 credit. The price varies logarithmically/exponentially between the maximum stock and zero stock, so that a decrease in the higher stock range results in less price increase.


production
------------

Controls the production of a good and its waste.

production=A,B*,C,D

A=String: Nickname of the good.
B*=Function: A function specification for the production. See below.
C=String: Nickname of a waste product during production.
D=Float: Number of waste products per item produced

Now column B is not a real column: The number of columns for B depends on the function used. The choice is the same as in good_relations.ini and the syntax is the same. Columns C and D may be repeated to cause any number of waste products to be created along with the main product.

So lets create an example:

produces=commodity_ship_hull_panels,periodic,25,5,20,commodity_toxic_waste,0.1,commodity_scrap_metal,0.2

This states that a market produces ship hull panels periodically with an average of 25 items a day and a std. deviation of 5. The period
length is 20 game days. As byproducts is an item of toxic waste produced for every 10 panels and one item of scrap metal is produced for
every 5 panels.



supply
-------

Controls the supply of goods by NPCs to the base.

supply=A,B,C*

A=String: Nickname of the good supplied.
B=Float: Number of supply ships per day (less than 1 means supply only every couple of days: 1/x == every x days a ship supplies these goods.)
C*=Function: Function specification for the supply. The function is evaluated according to column B. In most cases the supply will be constant.


demand
---------

Controls the supply of goods by NPCs to the base.

supply=A,B*

A=String: Nickname of the good supplied.
B*=Function: Function specification for the supply. The function is only evaluated once for a day.


sale
-----

Controls the number of goods sold by the trader to NPCs.

sale=A,B*

A=String: Nickname of the good sold.
B*=Function: Function specification for the sale. This function is evaluated every 18 seconds to determine the number of goods sold in the last 15 game minutes.


reputation
-------------

Controls how trading with a good affects the players reputation with the owners of the base.

reputation=A,B,C

A=String: Nickname of the good for which the reputation is set.
B=Factor: Multiplier for the number of goods traded.
C=Factor: Influence on the current reputation. A positive influence means that the reputation increases if the player buys the good and decreases if the player sells the good to the base. To turn this around use a negative value.



Ok that's it for today. This represents the structure for markets.ini. It is the file, which is the most difficult one. The next one will be way easier again, I'll post it next week. The stock of a good in base are influenced by a lot of factors in this file, but the price is mainly determined by the stock. The other fields (supply, demand, sale, production) mainly control the stock changes (and thus indirectly the price.)

As always post questions as replies.




Edited by - grover on 1/25/2006 12:52:53 AM

Edited by - grover on 1/25/2006 12:55:14 AM

Reserved

market_news.ini
==============

Since I was actually done earlier than expected with the market news tutorial, I'll post it today. This is the last INI file added by the FL Real Economy addon. The INI files from the previous posts allowed us to control various things around the economy, but they leave a little bit of a bad taste: They are predictable. Math is predictable. So this file will take care of that

The file I'm talking about is market_news.ini, it allows us to make the market unpredictable in many ways. But its role is: Support changing the settings provided by markets.ini at almost random points in time. To say it in clear: This file allows you to modify supply, demand, sale or production defined in markets.ini for certain periods of time for a base or the entire universe.

Not only can you affect those settings, but you can tell the player what happend: An event displayed in the News in any FL base. So what could you do with it? You could define an event, which tells the player that Liberty increased the patrols to scan for smugglers and cought a dozen cardamine carrying traders. The outcome could be that the supply of cardamine on bases in Liberty space is lower.

The other news could be that in order to contain the cardamine trade Liberty resorted to give out cardamine freely to those with addiction problems: The result could be a drop in demand and a drop in sales on bases selling cardamine. Its all up to you how creative you'll be with the events here.

Bad news: In order to display the actual news to the player you'll need to create a custom resource DLL with the ids_name and ids_info entries for the news. This is not included in the mod.


News Info Section
=================

So lets start with the first section in market_news.ini: The NewsInfo section. It looks like this:

[NewsInfo
category=ids_name
headline=ids_name
text=ids_name

It simply declares a category, headline and text, which FL Real Economy will use to display market news in. Say what? We'll the problem is: You can't simply add new news at runtime - The solution I'm working on replaces an existing news topic. To do this you need to define one full news entry in news.ini - The actual ids_name/ids_info used there have to exist. You should provide something like 'In a normal day of trading no unusual events happened.'. The category and headline should make sense generally speaking, as they are reused for every event specified below. In addition to this you need to add this news entry to all bases you want market news to appear in.

I have not yet figured out how to add an arbitrary number of news entries to the news screen, once I solve that this Hack won't be needed anymore - But currently we don't have any other option.


The fields:

category
----------

This is the category id of the market news item. This *MUST* be the same as specified in news.ini. FL Real Econ will not replace the category text. It is the same for *all* market news.

headline
----------

This is the headline id of the market news item. This *MUST* be the same as specified in news.ini. FL Real Econ will not replace the headline text. It is the same for *all* market news.

text
-----

This is the text id of the news item, FL Real Econ will replace. This *MUST* be the same as specified in news.ini.


FL Real Economy will provide proper market news *ONLY* for bases, which have a news entry, which matches the above three ids.


Ok now we've seen how FL Real Econ replaces an existing entry, but what does that mean for me? We'll the ids_info entries for new news look a little bit different.


Market News IDS_INFO format
===========================

You basically leave out the following things from a standard ids_info:

<?xml version="1.0"?>
<RDL>
<PUSH />

<POP />
</RDL>

FL Real Econ will take care to provide this stuff automatically for market news. Why is it doing this? Because multiple events can happen at the same time and they will both be included in the same news entry.

So your market news ids_info should look like this:

<TEXT>
My news text.
</TEXT>
<PARA/>

You can use all other attributes and tags - just make sure you leave out the root tag and that you add a <PARA/> element last.


We've now seen the way the news are displayed and how you can add custom news for the market. But how do you tell the market about events? Here comes the next section: MarketEvent.


Market Events
=============

Lets first look at the entire section:

[MarketEvent
headline = ids_name
text = ids_info
type = fixed,time,duration/periodic,start-time,periodlength,duration/random,probability,duration
affects = base,good,delay,[supply/demand/production/sale,[function

Ok now this does look simple, doesn't it? Yep, here are the details:

headline
----------

When I told you your market event didn't have its own headline - well I lied. It does have a headline, but it isn't display as the headline, but inserted by FL real econ into the text. This entry specifies the ids_name of the headline for this event.


text
------

This specifies the ids_info entry for the event. Make sure that it is in the right format (See above.)


type
-----

This specifies the type of the event, e.g. when it will appear. The options here are:

- fixed events - Occurs at a specific point in time and never again.
- periodic events - Occurs regularly for specific duration.
- random events - These occur randomly.

The format to declare them should be obvious from the above Section, however one note: For periodic events the periodlength specifies the time, which passes between the last time the event happend and the next time it will happen. All times can be expressed as floating point values and can span durations less than a day.

affects
--------

This line tells FL Real Econ, what is affected by the event. For example you could have an event, which affects the demand on one base and the supply in another base - a chain reaction if you will.

The format of the affects line is as follows:

affects=A,B,C,D,E*

A = nickname of the affected base.
B = The nickname of a good
C = Delay in *full* days (integer) from the start of the event to when the affects line will take effect.
D = A choice of one of these strings: supply, demand, sale, production.
E = A new function for the affected base in the affected case.

E.g. the following line:

affects=Li01_01_base,commodity_cardamine,0,demand,linear,10000,100000,10

causes the demand for cardmine on Manhattan to rise from an initial value of 10000 to 100000 over the next 10 days. The example doesn't really make sense, as the demand would all of the sudden drop from 100000 to the configured value in markets.ini after the ten days have passed. To get a nicer curve, which gets higher and then drops slowly back to the original use the periodic function and make the event duration (declared in the type field) half the length of the period length. That gives you a nice rise and fall before continuing with the normal markets.ini settings. (Look at the example below for this.)


So what can you do with all of these settings, we'll I'll give you an example:

[MarketEvent
headline = ids_name ; Cardamine addiction increased in Manhattan
text = ids_info ; Due to an unusual rock & roll event on Planet Manhattan experts said that the demand for cardmine is increased.
type = periodic,166,365,10
affects = Li01_01_base,commodity_cardamine,0,demand,periodic,10000,90000,20
affects = Li01_01_base,commodity_cardamine,1,supply,periodic,8000,58000,18
affects = Li01_12_base,commodity_cardamine,1,sale,periodic,50000,50000,20

Wow. What will this do:

We have a rock festival on Manhattan once a year. (It is in mid-june to be exact. ) And of course all those folks are going to listen to music, drink a lot and of course consume cardamine.

Here's what it will affect:

1. The demand of cardamine will rise along a nice sine curve over 5 days on Manhattan.
2. The supply of cardamine will rise, but not as much over 4 days. The rise is delayed by one day.
3. The sale of cardamine on buffalo will rise from 50000 to 100000 over 4 days. The sale is delayed by one day.

And after these 5 days are over everything drops back to normal levels. A predictable, but unpredictable event You see it and if you are fast enough your profits will be huge.

The number of things you can do with this is only limited by your imagination.

That's it for today. I may post another entry to explain the formulas used for price calculation or other stuff you'd like to see. I do not have any plans on filling the next two entries yet. Ask questions and you'll get answers or may be even an additional entry in the tutorial.

grover




Edited by - grover on 1/26/2006 2:15:41 AM

Edited by - grover on 1/26/2006 2:28:05 AM

How to install the addon
====================

The addon consists of a new DLL and a set of new INI-Files, which means that the
addon is a real addon:

- It does not modify any existing INI-Files (except dacom.ini/dacomsrv.ini)
- It can be activated or deactivated - the original economy in FL still works.

The addon consists of the following files:

- exe\fleconomy.dll
- data\equipment\good_relations.ini
- data\equipment\markets.ini
- data\equipment\market_news.ini

I may move the ini files to seperate directories, so that they are not mixed with the original ones, but that currently works for me.

To enable the new economy you only need to add one line to dacom.ini/
dacomsrv.ini, which is in section [Libraries

fleconomy.dll

This activates the addon. Thats it. If you want to deactivate the addon, either remove the line or comment it out by prepending a ; to it.

Now you've activated the addon, but you don't have the additional INI files required. What happens? Well the addon is activated, but it doesn't do anything. This allows you to introduce the new economy in steps and work with it in parallel to the old economic system in FL. If you don't configure a good for the new economic system, it won't be included and FL will still use the old economic system.



Edited by - grover on 1/20/2006 1:13:36 AM

Reserved

QA
==

Q: You are talking about a game day. What is it? How long is it?
A: Freelancer has its own time, where 1800 seconds (30 mins) correspond to one day on earth. All game day related values in the INI files are floating point numbers, which express the duration of something with respect to the games day.

Q: How often is the price calculation performed?
A: Price calculation is performed every 18 seconds, which corresponds to 15 minutes in our time. Almost real time. Additionally if you are currently trading, your trade will directly influence the price of a good in real time.

Q: Is this Multiplayer compatible?
A: Not currently, but the design has taken MP into account. I want to finish SP first and then port it to MP. The prices and stuff for MP will be calculated entirely on the server - the local files won't be necessary.

Q: I want to contribute to this project. How can I do this?
A: Sent me an email and we'll see. Tell me what you can do and how much time you have available.




Edited by - grover on 1/20/2006 1:22:18 AM

XOXOXOXOXOXO's

brilliant,just brilliant :}

Following this with great enthusiasm i have to say, will revolutionise trading in the game. Top man!

I've just posted the third and last INI file description in the tutorial. You now have all the information I can give you about the mod. If some description isn't clear or you have ideas to extend it reply to this thread.

This is a very interesting way to have a changing, fluxuating market in freelancer to make it more 'real'. I love the ideas on how supply and demand work. If enough pirates(or you) take out certain transports it should skyrocket a good through the roof.

Very very nice I must say...keep it up. I wish I had the time to help you test this out..

Hunting those above the law.

Protector and cofounder of the Hawk Trading Company found on Hals2003Evoserver.

First stupid question, what does the new dll do or store?

As I said in the tutorial it provides a new economy for FL. Nothing more, nothing less.

How I haven't read about this I don't know, it sounds completely fantastic, and very much needed for the Freelancer game. I'd love to help out in testing the thing if you need any extra help (although to be honest, I don't have all the time in the world, a few hours here and there due to uni + courseworks).

Regardless, I really look forward to hearing more details and updates about this, especially if it can be made MP compatible (which would completely, simply, and positively be the best development for FL ever. Period).