Various adjustments to improve trader efficiency in X4 Foundations.
- Our GitHub repo: https://github.com/Vectorial1024/v1024_logistics_optimization
- Detailed changelog: https://github.com/Vectorial1024/v1024_logistics_optimization/blob/master/CHANGELOG.md
- Advanced users may make use of commit tags
- Our EgoSoft Forums link: https://forum.egosoft.com/viewtopic.php?t=471490
- Our Steam Workshop link: https://steamcommunity.com/sharedfiles/filedetails/?id=3496466928
- Our Nexus Mods link: https://www.nexusmods.com/x4foundations/mods/1719
Improve your station traders; improve your trade stations!
(Actually, NPC station traders are also improved, but eyyy.)
TL;DR: no player action needed! Also perfectly save-compatible!
This mod modifies the vanilla trading scripts to improve trader efficiency, and so allows logistics to work better.
The changes made by this mod can be summarised into several "bundled modules":
- Faster Trade Matching: station traders idle less when searching/matching trade offers
- Counter Trend Trading: some station traders reprioritize their work to stabilize station production
- Full Load Delivery: M/L/XL station traders dislike unused cargo space
- Patient Opportunists: station traders randomly go further for trades
- (more WIP...)
Each such module will have its own README section below.
With this mod, perhaps you have less need for custom trading scripts (e.g. TaterTrader, the Mules, etc.).
This mod is a spiritual successor of Civilian Fleets, a 1.0-era mod that was eventually adapted into the base game as of the 7.0 update.
Following the dissolution of Civilian Fleets, the deprecated fleets of old were reorganized to serve several new trade stations. However, it was noticed that station-based traders (especially trading-station traders) are behaving... not as expected. They are consistently making trade deals that are apparently unoptimal.
This causes larger-scale logistics problems.
While there are other custom trading scripts to help with these logistics problems, they are often tedious to configure and manage (e.g. usually exists as separate fleets, causing cluttering). It would be best if the vanilla one just "works", so these tedium may vanish.
It was eventually discovered/determined that the vanilla station trading logic can be improved, which motivated the creation of this mod.
Reduce the undocumented idling time of station traders.
The relevant parts of the vanilla station trader logic is roughly as follows:
- Station traders find trades one-at-a-time to prevent trade stampeding
- When a station trader is finding trades, it iterates through the tradeable ware list first, and then the trade partner sector
- There are some idling after completing the search on the ware/sector
The concern is that if the ware list is long and the sector coverage is wide (e.g. regional trade hub), then traders may spend too long trying to confirm a trade run.
As such, this mod reduces the idling time of station traders.
On the "hidden timer" of the "one-at-a-time" rule
There is an undocumented timer that station traders use to wait for their chance to be the "one-at-a-time" trader to find trades:
- Station traders try to "acquire the lock" (managed by the station) when they start their work
- If successful, then the trader stops waiting and starts finding trades
- When trade finding completes, the trader frees the lock
- Unsuccessful locking will put the trader to a 30-round random-sleep
- Vanilla numbers means a maximum random(1.5mins, 5.5mins) of waiting time here
- If the timer runs out and still no locks acquired, the now "bored" trader goes YOLO to find trades regardless
- This may cause unrecoverable general lag!
Because of the "Patient Opportunists" module below, this timer has been increased to spread out the calculation even more.
In theory, reducing idling time may momentarily decrease performance (aka "cause lag spikes") when station traders are finding trades.
Station traders now have a small chance to engage in so-called "counter-trend" trading (elaborated in Technical Info below).
This counter-trend trading occurs only once per trade search. (Note: "no trades found" failure does not end the search!)
This works alongside the "prioritize shortage" vanilla behavior.
The relevant parts of the vanilla station trader logic is roughly as follows:
- Station traders wait for their turn to find trades
- Check whether there is a shortage; if exists, stop and handle it (added since 7.0)
- Check whether some wares can be exported; if exists, stop and handle it
- Check whether some wares can be imported; if exists, stop and handle it
It should be noted that station traders follow this procedure very rigidly, leading to the following behavior (assume no outside help):
- Station is producing normally: traders ignore the ingredients, leading to eventual shortage, which may stop production
- Station ran out of ingredients: traders ignore the products, leading to reduced cash, which may actually prevent resumption
These behaviors result in stations often swinging wildly between "overworked" and "frozen", with each state being difficult to autonomously recover from. This then destabilizes the supply chain even when resources are obviously available.
By having some (not all) station traders prioritize counter-trend trading, these swings should happen less, so station production can be greatly stabilized.
No performance impact expected since this is only a reordering of inevitable events.
Mid-large (i.e. M/L/XL) station traders dislike unused cargo space.
Small (i.e. S) traders are excluded because they are small and fast:
- Their small cargo size means they are very likely to run around with full load anyway
- Their high speed makes up for potential low-usage cargo runs
- Thus, their role is to fulfill small-volume trade deals which larger traders dislike
This module inherits the mod Fully Loaded for better management.
The relevant parts of the vanilla station trader logic is roughly as follows:
- When a trade offer is available, the trader calculates a trade value:
Trade value = Total cargo space used * Relative price margin
- The trade offer with the best trade value is selected, and the trader then makes the correct trade reservations
The concern is that, there is nothing to prevent traders from selecting juicy but small offers over large but bland offers. This causes mid-large traders to run around with very low cargo space usage just because the relative margin is great.
In vanilla, some of the ware categories with the greatest price ranges (i.e. max price / min price) are:
- Drugs (~3.4x) (note: does not include Black Market additional markups, which would push range to ~5.5x)
- Food, Water and Energy (~2.3x)
- Refined Goods (~2.3x) (e.g. Refined Metals, Antimatter Cells, etc.)
Mid-large traders dealing with these wares will likely be inefficient with their cargo space usage.
This problem can be easily fixed by scaling down the trade value if the proposed trade offer uses very few cargo space.
No performance impact expected since this is just a change of calculation formula.
Station traders may randomly extend their trade search to hopefully find better trades; exact chances depend on the ship class and the station trade range.
The chances and effects of search extension is documented below:
(Each cell contains (chance of extended search, number of additional sectors to search if extended search))
| Trade range | S-Class | M-Class | L-Class | XL-Class |
|---|---|---|---|---|
| 0 Sectors | (0%, +0) | (0%, +0) | (0%, +0) | (0%, +0) |
| 1 Sector | (4%, +1) | (8%, +1) | (8%, +1) | (8%, +1) |
| 2 Sectors | (7%, +2) | (15%, +2) | (15%, +1) | (15%, +1) |
| 3 Sectors | (10%, +3) | (21%, +3) | (21%, +2) | (21%, +2) |
| 4 Sectors | (13%, +4) | (26%, +4) | (26%, +2) | (26%, +2) |
| 5+ Sectors | (15%, +5) | (30%, +5) | (30%, +3) | (30%, +3) |
You may observe the following:
- L/XL traders do not want to go too far away because they are usually slow
- S traders are less likely to extend searches because of their very limiting cargo hold and their general fragility
With this, the trader's ship class becomes important. Ideally, most traders should be M traders, with a bit of S/L traders to handle niche cases.
This interacts with other modules in this mod, e.g. L/XL traders will want to quickly find trade offers among several sectors that can fill up its cargo hold.
The relevant parts of the vanilla station trader logic is roughly as follows:
- Select a ware from commander station to find matching external trade offers
- Then, iterate through the in-range sectors list, closest sector first:
- Then, iterate through the external trade offers in the sector:
- Find and select the best trade offer using the trade value formula mentioned above
- Then, iterate through the external trade offers in the sector:
The problem is that, this is a greedy algorithm. With this greedy algorithm, station traders will always buy out closer trade offers, and will generally refuse to consider cheaper trade deals that are slightly further away.
This can be easily alleviated by telling station traders to find trade offers from several sectors, then find the best offer among them.
A larger trade range warrants a more extended search, but to avoid potential supply failure because everyone is all in transit and unavailable, this search extension does not trigger every time.
Low performance impact expected. While extended trade searches is an expensive operation, it is mostly limited by the "1 thinking trader only" rule as described above.