Pyanodon's Caravan Swarm

Automatic logistics for Pyanodon's caravans, in the spirit of LTN and Cybersyn.

No more schedules and no more caravan loops. Give each outpost a role and a list of what it needs, and the swarm does the rest. It matches every need to the nearest supply, sends the nearest free caravan, keeps heavy items flowing through Storage, clears byproducts before they clog your outposts, sends hungry caravans to eat and tells you exactly where your factory is short and why.

Features

• Hands-off caravans. Switch a caravan into the swarm and it takes jobs by itself.
• Rates or amounts. Ask for each item per second, minute or hour, or keep a fixed amount in stock.
• Real buffering. Storage outposts hold one item each, fill up from Providers and serve Requesters first. Optional buffer caravans keep heavy items like coal and stone coming.
• Byproduct handling. Ash and other byproducts are used first and emptied into Storage or Dumps before they block production.
• Bottleneck reports. A full window with Overview, Bottlenecks, Outposts, Network, In transit, Jobs and Help tabs.
• Clickable alerts. Every problem gets an alert and a chat line that takes you straight to the outpost.
• Predictable. Every rule is fixed. Nothing learns or drifts over time.
• Light on UPS. The swarm runs on one tick in 30 and reads only what it needs.

Installation

Requirements

• Factorio 2.1
• Pyanodon's Alien Life 3.1.8, with the caravan add-on patch (see below)

Why a patch is needed

In Factorio every mod runs separately and cannot touch another mod's data. Caravans live inside pyalienlife, so the swarm has to run inside pyalienlife too, and pyalienlife has no way to load another mod's script yet.

The patch adds that, in five lines. It loads caravan add-ons that other mods declare and does nothing when none are installed. It has been proposed to the Pyanodon team as a pull request: pyanodon/pyalienlife#645. Once it is merged and released, the official pyalienlife will work as it is and this step goes away.

Getting the patch

Option A, ready-made. Download pyalienlife_3.1.8.zip and use it in place of the official file in your mods folder. It is Py's 3.1.8 with the five lines added and nothing else changed.

Option B, patch your own copy. Download pyalienlife-caravan-swarm-patch.zip. It holds only the one changed file and a short guide. Or skip the download and add the lines yourself: open scripts/caravan/caravan.lua inside your pyalienlife_3.1.8.zip, find the line require "manager" and paste this directly below it:

-- Caravan add-ons: a mod can run its own caravan scripts here, next to the caravans they extend, by declaring a
-- mod-data prototype with data_type = "py-caravan-addon" and data = {script = "__its-mod__/path/to/file"}.
for _, addon in pairs(prototypes.mod_data) do
    if addon.data_type == "py-caravan-addon" and addon.data.script then require(addon.data.script) end
end

Good to know

• Stay on pyalienlife 3.1.8 until the patch is released officially. If an update replaces your patched copy, the swarm shows a red warning in chat and pauses. Nothing breaks. Patch it again and it carries on.
• Report errors here, not to Py. The swarm runs inside pyalienlife, so its bugs can appear as pyalienlife errors. If you see one with the swarm installed, please report it on this page.

Quick start

1. Feed your caravans. Set an outpost's role to Food depot and stock it with caravan food.
2. Add caravans. Open a caravan and click the Swarm switch next to its name. To add many at once, Shift + right-click a swarm caravan, then Shift + left-click the others.
3. Give outposts roles. Open each outpost and pick its role in the swarm panel on the right.

That's it. The swarm decides which caravan goes where.

Open the swarm window with the caravan button at the top left, the toolbar shortcut, Ctrl + Alt + V or /swarm. Its Help tab covers everything on this page.

Outpost roles

Fluid tanks work the same way. Pick the fluid and the role.

Requesters

Add an item with the empty slot under the list, then give it a Rate or an Amount.

• Rate is how fast your factory uses the item. 2 means 2 per second. You can add a time: 1/5s is one every 5 seconds, 0.5/m is half per minute, 2/h is two per hour.
• Amount is how many to keep there, for example 400.

A rate becomes an amount of about 4 minutes of use, more when trips are long, so 0.2/s keeps 48. A caravan brings more once half the amount is gone: an amount of 400 is topped up when it drops to 200.

Click a box to type. Enter or a left click anywhere saves it, and a right click cancels. The list shows what is in stock, what is on the way and the average that actually arrived.

When the items need more slots than the outpost has, each gets a fair share of the slots. The rest waits on caravans parked outside, which unload as room frees up and count as part of the stock.

Storage

A Storage keeps one item, picked with the button next to its role. Every slot is filtered for it, and it orders more from Providers once half empty.

Buffer caravans are for heavy items like coal or stone that drain a Storage faster than one trip refills it. Set a number with the - and + on the Storage's panel and that many extra loads are kept coming. They wait in line while the Storage is full and unload as it drains. Can move shows how much the Storage can pass on per second. Leave it at 0 for everything else.

A Provider that reaches 3/4 full pushes its extra into a Storage of that item, down to half, so the factory behind it never stops.

Byproducts and Dumps

Every Requester and Storage takes from Byproduct outposts first, so byproducts get used instead of piling up. At 3/4 full a Byproduct outpost is emptied, first into a Storage of that item, then into a Dump.

A Dump takes either only the items you list or everything except them, and a Dump that lists the item is picked first. Dumps are watched through the caravans waiting at them: Slow means caravans wait long to unload, Halted means nothing unloads at all.

The swarm window

• Overview: busy and free caravans, and everything delivered.
• Bottlenecks: every problem, worst first, with buttons to the outpost. It tells you whether an item is short because nothing makes it, supply is too slow or no caravan is free, and flags Requesters that ask for too little.
• Outposts: the busiest outposts, filtered by type.
• Network: every item in the swarm and where it is.
• In transit: what caravans carry right now.
• Jobs: every trip, problems first.
• Help: everything on this page, in game.

Alerts and warnings

The swarm watches itself. When something goes wrong it tells you what, where and usually why, so a problem never hides behind hundreds of busy caravans. Alerts appear in the game's alert bar, with a chat line you can click to jump there. Each one clears by itself once the problem is gone.

Alerts

The Bottlenecks tab

Every problem, worst first, each with a button that takes you to the outpost:

• Items short at Requesters, with the reason: Nothing makes it (no Provider holds it), Best supplier has X, a trip needs Y, No free caravan can carry it or Supply too slow (caravans waiting at the Provider for their load).
• Byproducts that cannot be emptied, and Dumps that are Slow or Halted.
• Requesters asking for too little, kept apart from supply problems so you know which side to fix.
• Requester and Storage outposts asking for nothing, so a forgotten setup does not go unnoticed.

Caravan status

Every swarm caravan's window says what it is doing: waiting for work, picking up, delivering, emptying a byproduct outpost, going to eat, out of food at a Food depot, or holding leftover cargo while it waits for a Dump.

Chat notices

• A swarm caravan's stops were edited by hand: the edit is undone and chat says so. Turn its Swarm switch off to drive it yourself.
• Cargo put into a swarm caravan by hand is handed back. Swarm caravans only carry what the swarm loads.
• pyalienlife without the patch: a red warning when the game loads, and the swarm pauses until the patch is back.

FAQ

Will it slow my game down?
It is built to stay light. The swarm works every 2 seconds, split into 4 steps, so it runs on one tick in 30 and reads only what it needs.

Does it learn or measure my factory?
No. Every rule is fixed: how full an outpost is, the amounts you set and distances. It only measures trip times, to size rate amounts safely, and the statistics shown in the window.

Is the patch safe?
It runs once when the game loads and does nothing unless an add-on is installed. On its own it changes nothing in your game.

Does it work in multiplayer?
Everything it decides with is saved with the game, so all players see the same thing. So far it has only been tested in single player.

What if caravans run out of food?
A caravan only takes a job if it has enough food for the whole trip. Hungry caravans walk to the nearest Food depot on their own.

Can I still drive caravans by hand?
Yes. Caravans with the Swarm switch off are never touched. Switch a swarm caravan off to use it yourself.

How many caravans do I need?
Enough that some are always free. The window shows free caravans at the top, and an outpost gets a "No free caravan" alert when none is available.

Will a caravan cross the map for a handful of items?
No. Requesters reorder once half their amount is gone and Storage once half empty, so every trip carries a worthwhile load.

Why do caravans wait outside a full outpost?
They count as part of its stock and unload as soon as there is room.

What happens if I remove an item from a Requester?
Caravans not yet loaded are cancelled. Loaded ones go to another outpost that wants the item, or wait with an alert if none does.

Does it work with caravan speed or hitbox mods?
Yes. It reads each caravan's real speed and measures real trip times.

Can it deliver between surfaces?
No. Each delivery stays on one surface.

What if I remove the mod?
Roles stay in the save. Caravans finish their current stops and then stand still. Add the mod back and it picks up where it left off.

Feedback and bug reports

Bug reports and ideas are welcome in the Discussion tab. With a bug report, please attach the file written by the /swarm-report command. It is a snapshot of your swarm and makes problems much easier to track down.

Credits

Pyanodon's Alien Life and its caravans are the work of the Pyanodon team. Caravan Swarm builds on their work and is not an official Pyanodon mod.

AI disclosure

Caravan Swarm was made with the help of AI. The code was written with Anthropic's Claude under my direction. I designed how it works, made every decision and tested it in my own Pyanodon game.