{"id":30327296,"url":"https://github.com/vectorial1024/v1024_logistics_optimization","last_synced_at":"2026-02-11T09:03:14.322Z","repository":{"id":298239917,"uuid":"999307302","full_name":"Vectorial1024/v1024_logistics_optimization","owner":"Vectorial1024","description":"Various adjustments to improve trader efficiency in X4 Foundations","archived":false,"fork":false,"pushed_at":"2025-06-25T05:21:28.000Z","size":948,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-09-03T13:07:45.153Z","etag":null,"topics":["mod","x4foundations"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Vectorial1024.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-10T04:09:03.000Z","updated_at":"2025-08-24T17:00:53.000Z","dependencies_parsed_at":"2025-06-25T05:19:03.371Z","dependency_job_id":"355f5aa5-5d6b-4b16-9f23-d25720d8f41e","html_url":"https://github.com/Vectorial1024/v1024_logistics_optimization","commit_stats":null,"previous_names":["vectorial1024/v1024_logistics_optimization"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/Vectorial1024/v1024_logistics_optimization","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Vectorial1024%2Fv1024_logistics_optimization","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Vectorial1024%2Fv1024_logistics_optimization/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Vectorial1024%2Fv1024_logistics_optimization/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Vectorial1024%2Fv1024_logistics_optimization/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Vectorial1024","download_url":"https://codeload.github.com/Vectorial1024/v1024_logistics_optimization/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Vectorial1024%2Fv1024_logistics_optimization/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29330858,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-11T06:13:03.264Z","status":"ssl_error","status_checked_at":"2026-02-11T06:12:55.843Z","response_time":97,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mod","x4foundations"],"created_at":"2025-08-18T00:09:51.627Z","updated_at":"2026-02-11T09:03:14.308Z","avatar_url":"https://github.com/Vectorial1024.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Logistics Optimization\nVarious adjustments to improve trader efficiency in X4 Foundations.\n\n- Our GitHub repo: https://github.com/Vectorial1024/v1024_logistics_optimization\n  - Detailed changelog: https://github.com/Vectorial1024/v1024_logistics_optimization/blob/master/CHANGELOG.md\n  - Advanced users may make use of commit tags\n- Our EgoSoft Forums link: https://forum.egosoft.com/viewtopic.php?t=471490\n- Our Steam Workshop link: https://steamcommunity.com/sharedfiles/filedetails/?id=3496466928\n- Our Nexus Mods link: https://www.nexusmods.com/x4foundations/mods/1719\n\n\u003e Improve your station traders; improve your trade stations!\n\n(Actually, NPC station traders are also improved, but eyyy.)\n\n------\n\n## Quick Info\nTL;DR: no player action needed! Also perfectly save-compatible!\n\nThis mod modifies the vanilla trading scripts to improve trader efficiency, and so allows logistics to work better.\n\nThe changes made by this mod can be summarised into several \"bundled modules\":\n- Faster Trade Matching: station traders idle less when searching/matching trade offers\n- Counter Trend Trading: some station traders reprioritize their work to stabilize station production\n- Full Load Delivery: M/L/XL station traders dislike unused cargo space\n- Patient Opportunists: station traders randomly go further for trades\n- (more WIP...)\n\nEach such module will have its own README section below.\n\nWith this mod, perhaps you have less need for custom trading scripts (e.g. TaterTrader, the Mules, etc.).\n\n## Motivation\nThis 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.\n\nFollowing the dissolution of Civilian Fleets, the deprecated fleets of old were reorganized to serve several new trade stations.\nHowever, it was noticed that station-based traders (especially trading-station traders) are behaving... not as expected.\nThey are consistently making trade deals that are apparently unoptimal.\n\nThis causes larger-scale logistics problems.\n\nWhile there are other custom trading scripts to help with these logistics problems, they are often tedious to configure and manage\n(e.g. usually exists as separate fleets, causing cluttering). It would be best if the vanilla one just \"works\", so these tedium may vanish.\n\nIt was eventually discovered/determined that the vanilla station trading logic can be improved, which motivated the creation of this mod.\n\n------\n\n## Faster Trade Matching\nReduce the undocumented idling time of station traders.\n\n### Technical Information\nThe relevant parts of the vanilla station trader logic is roughly as follows:\n- Station traders find trades one-at-a-time to prevent trade stampeding\n- When a station trader is finding trades, it iterates through the tradeable ware list first, and then the trade partner sector\n- There are some idling after completing the search on the ware/sector\n\nThe 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.\n\nAs such, this mod reduces the idling time of station traders.\n\n### On the \"hidden timer\" of the \"one-at-a-time\" rule\nThere is an undocumented timer that station traders use to wait for their chance to be the \"one-at-a-time\" trader to find trades:\n- Station traders try to \"acquire the lock\" (managed by the station) when they start their work\n  - If successful, then the trader stops waiting and starts finding trades\n  - When trade finding completes, the trader frees the lock\n- Unsuccessful locking will put the trader to a 30-round random-sleep\n  - Vanilla numbers means a maximum random(1.5mins, 5.5mins) of waiting time here\n- If the timer runs out and still no locks acquired, the now \"bored\" trader goes YOLO to find trades regardless\n  - This may cause unrecoverable general lag!\n\nBecause of the \"Patient Opportunists\" module below, this timer has been increased to spread out the calculation even more.\n\n### Expected Performance Impact\nIn theory, reducing idling time may momentarily decrease performance (aka \"cause lag spikes\") when station traders are finding trades.\n\n------\n\n## Counter Trend Trading\nStation traders now have a small chance to engage in so-called \"counter-trend\" trading (elaborated in Technical Info below).\n\nThis counter-trend trading occurs only once per trade search. (Note: \"no trades found\" failure does not end the search!)\n\nThis works alongside the \"prioritize shortage\" vanilla behavior.\n\n### Technical Information\nThe relevant parts of the vanilla station trader logic is roughly as follows:\n- Station traders wait for their turn to find trades\n- Check whether there is a shortage; if exists, stop and handle it (added since 7.0)\n- Check whether some wares can be exported; if exists, stop and handle it\n- Check whether some wares can be imported; if exists, stop and handle it\n\nIt should be noted that station traders follow this procedure very rigidly, leading to the following behavior (assume no outside help):\n- Station is producing normally: traders ignore the ingredients, leading to eventual shortage, which may stop production\n- Station ran out of ingredients: traders ignore the products, leading to reduced cash, which may actually prevent resumption\n\nThese behaviors result in stations often swinging wildly between \"overworked\" and \"frozen\", with each state being difficult to autonomously recover from.\nThis then destabilizes the supply chain even when resources are obviously available.\n\nBy having some (not all) station traders prioritize counter-trend trading, these swings should happen less, so station production can be greatly stabilized.\n\n### Expected Performance Impact\nNo performance impact expected since this is only a reordering of inevitable events.\n\n------\n\n## Full Load Delivery\nMid-large (i.e. M/L/XL) station traders dislike unused cargo space.\n\nSmall (i.e. S) traders are excluded because they are small and fast:\n- Their small cargo size means they are very likely to run around with full load anyway\n- Their high speed makes up for potential low-usage cargo runs\n- Thus, their role is to fulfill small-volume trade deals which larger traders dislike\n\nThis module inherits the mod Fully Loaded for better management.\n\n### Technical Information\nThe relevant parts of the vanilla station trader logic is roughly as follows:\n\n- When a trade offer is available, the trader calculates a trade value:\n  - `Trade value = Total cargo space used * Relative price margin`\n- The trade offer with the best trade value is selected, and the trader then makes the correct trade reservations\n\nThe concern is that, there is nothing to prevent traders from selecting juicy but small offers over large but bland offers.\nThis causes mid-large traders to run around with very low cargo space usage just because the relative margin is great.\n\nIn vanilla, some of the ware categories with the greatest price ranges (i.e. `max price / min price`) are:\n- Drugs (~3.4x) (note: does not include Black Market additional markups, which would push range to ~5.5x)\n- Food, Water and Energy (~2.3x)\n- Refined Goods (~2.3x) (e.g. Refined Metals, Antimatter Cells, etc.)\n\nMid-large traders dealing with these wares will likely be inefficient with their cargo space usage.\n\nThis problem can be easily fixed by scaling down the trade value if the proposed trade offer uses very few cargo space.\n\n### Expected Performance Impact\nNo performance impact expected since this is just a change of calculation formula.\n\n------\n\n## Patient Opportunists\nStation traders may randomly extend their trade search to hopefully find better trades; exact chances depend on the ship class and the station trade range.\n\nThe chances and effects of search extension is documented below:\n\n(Each cell contains `(chance of extended search, number of additional sectors to search if extended search)`)\n\n| Trade range | S-Class | M-Class | L-Class | XL-Class |\n| -------- | ------- | ------- | ------- | ------- | \n| 0 Sectors | (0%, +0) | (0%, +0) | (0%, +0) | (0%, +0) |\n| 1 Sector | (4%, +1) | (8%, +1) | (8%, +1) | (8%, +1) |\n| 2 Sectors | (7%, +2) | (15%, +2) | (15%, +1) | (15%, +1) |\n| 3 Sectors | (10%, +3) | (21%, +3) | (21%, +2) | (21%, +2) |\n| 4 Sectors | (13%, +4) | (26%, +4) | (26%, +2) | (26%, +2) |\n| 5+ Sectors | (15%, +5) | (30%, +5) | (30%, +3) | (30%, +3) |\n\nYou may observe the following:\n- L/XL traders do not want to go too far away because they are usually slow\n- S traders are less likely to extend searches because of their very limiting cargo hold and their general fragility\n\nWith 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.\n\nThis 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.\n\n### Technical Information\nThe relevant parts of the vanilla station trader logic is roughly as follows:\n- Select a ware from commander station to find matching external trade offers\n- Then, iterate through the in-range sectors list, closest sector first:\n  - Then, iterate through the external trade offers in the sector:\n    - Find and select the best trade offer using the trade value formula mentioned above\n\nThe problem is that, this is a greedy algorithm. With this greedy algorithm, station traders will always buy out closer trade offers,\nand will generally refuse to consider cheaper trade deals that are slightly further away.\n\nThis can be easily alleviated by telling station traders to find trade offers from several sectors, *then* find the best offer among them.\n\nA larger trade range warrants a more extended search, but to avoid potential supply failure because everyone is all in transit and unavailable,\nthis search extension does not trigger every time.\n\n### Expected Performance Impact\nLow 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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvectorial1024%2Fv1024_logistics_optimization","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvectorial1024%2Fv1024_logistics_optimization","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvectorial1024%2Fv1024_logistics_optimization/lists"}