Equilibrium · Beginner · Tutorial 1 of 3

Your iron ore is about to lose
93% of its value in one tick.

That is not a bug, and it is not the simulation being dramatic. It is arithmetic you can do on paper, and once you can do it you can predict your own economy instead of watching it happen to you.

Application AshForge Equilibrium Prerequisites none Format run → predict → verify Time ~20 min

What Equilibrium is

An economy simulator for your mod. You describe resources, the markets that trade them, and the recipes that turn one into another; it runs supply and demand over them a tick at a time and hands the result to the game.

This first tutorial stays on one idea: what a single tick does to a price. Everything else in the tool — markets, arbitrage, supply chains, shocks — is that one calculation applied more times and in more places.

Before you start

Open Equilibrium from the Hub. It seeds a small demo economy on first run: three resources and one market. You will not need the game installed.

One habit worth bringing: read the log strip along the bottom of the window. Equilibrium narrates what it did there, and it is the only place some of it appears.

Read first

Undo works, but it never reaches the file. Pressing Undo genuinely restores the previous state in the window — and it deliberately marks the project clean, so nothing is written to disk afterwards.

That means if you undo something and then close the tool without making another edit, the file still holds the thing you undid, and reopening brings it straight back. I watched a window showing three resources reload as five. If an undo matters, make one more edit afterwards — or press Save — so the corrected state is the one on disk.

What ships in the box

The demo economy

Read 3 resources 1 market

The list on the left holds both resources and markets, tagged [R] and [M]. On a fresh project it reads like this, and the numbers in brackets are stock and unit value.

[R] Iron Ore       (200 @ 1.50)
[R] Food Rations   (150 @ 3.00)
[R] Luxury Spices  (40 @ 12.00)
[M] Frontier Outpost (2 offers)

What the list does not show you is the field that decides everything, so it is worth knowing before you press anything: every one of those resources has a Demand of 50. Not because someone chose 50 for iron and again for spices, but because 50 is the model's default and the demo never overrides it.

Hold that next to the stock column. Iron Ore has four times more stock than demand. Food Rations has three times. Luxury Spices has less stock than demand. Those three relationships are the entire plot of what happens next.

Key

A resource's price does not move because of its category, its weight, or how expensive it already is. It moves on the gap between Demand and Stock, and nothing else in this model.

Run Sim

One tick

Run one press

Press Run Sim once. The log strip reports two things, and the second one matters as much as the first.

[INFO] (Shell) Economy simulation step executed (nonblock + conditions + cancel support).
[INFO] (EquilibriumStore) Saved Economy project 'Unnamed Mod' to …/equilibrium/economy

So a sim step is also a save. There is no separate "commit this run" — the tick happens and the result is on disk before you have finished reading the line.

Now look at the list again.

Resource	Before	After one tick	What happened
Iron Ore	200 @ 1.50	192.5 @ 0.10	Massively oversupplied, so the price fell as far as it is allowed to.
Food Rations	150 @ 3.00	145 @ 2.00	Oversupplied, so the price fell by a third.
Luxury Spices	40 @ 12.00	40.5 @ 12.10	Scarce, so the price rose.

Iron Ore lost 93% of its value in a single tick, which looks alarming and is the most common reason someone decides the simulation is broken. It is not. Here is the whole calculation the tool performs on every resource, every tick.

Figure 01 — one tick, one resource Elasticity and Global Elasticity both default to 1, and Trade Impact to 0.05, so on a fresh project the price adjustment is simply the imbalance divided by a hundred.

The floor

That max(0.1, …) is a hard floor. Iron Ore's adjustment was exactly −1.50 against a value of 1.50, which lands on zero, and the floor catches it at 0.10. A resource in this model can become nearly worthless but never free.

The test that proves you understand it

Predict the next one

Do paper first

Reading a formula is not the same as believing it. So before you press Run Sim a second time, work out what it is going to do and write the numbers down.

On paper

For each resource, in this order

Subtract its current stock from 50. Demand is still 50 — nothing in a sim tick changes it
Divide that by a hundred, and add it to the current value. elasticity and global elasticity are both 1 on a fresh project
If the answer is below 0.1, write 0.1. the floor
Multiply the same imbalance by 0.05 and add it to the stock. Trade Impact — supply drains toward demand as well

Resource	Standing at	You should predict	The tool produced
Iron Ore	192.5 @ 0.100	185.375 @ 0.100	185.375 @ 0.100
Food Rations	145.0 @ 2.000	140.250 @ 1.050	140.250 @ 1.050
Luxury Spices	40.5 @ 12.100	40.975 @ 12.195	40.975 @ 12.195

Verified

Those predictions were written down before the second tick was run, and the tool matched every one of them to three decimal places. The model is fully deterministic, which means from here on you are not guessing at your economy — you can work out where it is heading and check whether that is what you wanted.

03b

The one thing that isn't deterministic

Each tick, before any of the above, the tool rolls once against Shock Prob — 0.3 by default. On a hit it picks one resource at random and multiplies its stock by 0.6, then writes an Event row into the trade ledger reading “Shortage on <resource>!”.

Neither of the two ticks above rolled a shock, which is why the arithmetic came out clean. If your numbers disagree with your prediction by a suspiciously round 40%, check the ledger before you check your maths.

Key

If you want a predictable economy while you are learning the tool, set Shock Prob to 0 in Sim Settings. Put it back when you want to find out whether your design survives a bad harvest.

On disk

Where it all lives

Read 3 files

Equilibrium does not keep your economy in one blob. It splits it three ways, under equilibrium/economy in the tool's data folder, and the split is worth knowing because it tells you what the tool thinks the parts are.

File	Holds	Useful because
`resources.economy.json`	Every resource: stock, value, demand, elasticity, weight, category.	This is where you can read the real numbers when the list's rounding hides them.
`markets.economy.json`	Markets, their price bias, and their offers.	Offers reference a resource by name, so renaming a resource matters here.
`state.economy.json`	The wallet, player stock, sim parameters, price history, recipes, trade ledger.	Price history is a plain series per resource — the raw material for a chart.

The list on the left rounds for display: Iron Ore reads 185 @ 0.10 while the file holds 185.375. For a first tutorial that does not matter, but the moment you start checking your own predictions it does, and the file is where the honest number is.

Careful

Everything above is written by an autosave. An Undo is the one action that changes the window without changing those files — see the warning at the top of this page.

✓

Tier one complete

What you now know

Check yourself

Price moves on the gap between Demand and Stock, and on nothing else in this model.
The demo ships every resource at the default Demand of 50 against stocks of 200, 150 and 40, which is why two prices collapse on the first tick and one rises.
The adjustment is imbalance × 0.01 × elasticity, and the result is clamped to a floor of 0.1.
Stock moves too, by imbalance × TradeImpact, so supply drains toward demand as well as price falling toward it.
You can predict a tick on paper and be right to three decimal places, provided no shock fires.
A shock has a 30% chance per tick and multiplies one random resource's stock by 0.6, logged in the ledger as an Event.
Run Sim also saves. The economy lives in three files, and the list rounds where the files do not.
Undo restores the window but not the file, so follow an undo that matters with a save.

Next, at intermediate: markets. Why the Buy and Sell buttons do nothing while a resource is selected, what a market's price bias does to the numbers you just learned to predict, and how two markets trading the same resource turn transport cost into arbitrage.