Caravans & Convoys - Automatic Trade

Source & full guide: github.com/teamdemivfxfish-dev/caravans-and-convoys-wiki

Place a dock, post an offer, and let horse-drawn wagons run your trade routes for you.

Caravans & Convoys turns two chests in different places into a living trade route. You set what a Caravan Dock sends and what it wants back; from then on a real horse-drawn wagon, driven by its own coach and guarded by soldiers, hauls the goods overland on its own. Nothing teleports. Every trade rides a real wagon down a real, road-aware route, so a caravan can be raided, stranded, or wrecked before it ever arrives. No hoppers strung across the map, no manual shuttling, just wagons on the road.

Everything is standalone. It works in any world, reads your existing chests without ever owning them, and leans on other mods only when you actually have them installed.

Dependencies

Read this first so your caravans have something to drive.

Every integration is reflective, so there are no external Maven coordinates and the mod compiles and boots against pure NeoForge.

The Caravan Dock

• Found in the Functional Blocks creative tab.
• Crafts in a standard grid: three Planks across the top, a Chest flanked by two Planks in the middle, three Iron Ingots along the bottom. Yields one Caravan Dock.
• Clamps onto the first adjacent inventory (chest, barrel, MineColonies rack) and reads it through the standard item capability only, so hoppers, storage mods, and MineColonies couriers keep working exactly as before.
• A shop-style terminal where you set an Export (what you send) and an Import (what you want back), each an exact item and amount. Clicking a held item onto a ghost slot copies the item type only and never consumes the stack.
• Owner-claimed. Only the player who placed it can right-click to open the terminal; the settings tab holds the whitelist and a self-trade toggle.

The Freight Dock: hauling with no trade attached

Sometimes you just want the goods moved. A mining outpost tips its output into a chest and sends it home; the home base sends food back out to feed a colony. No offers, no payment, no partner to agree terms with.

• Crafts like the Caravan Dock with a Barrel in the middle instead of a Chest.
• Every Freight Dock has its own freight code. Give a dock another dock's code as its destination and its wagon hauls whatever lands in its chest over to that dock's chest, round after round, and comes home empty.
• A dock with no destination is a receiving depot. A dock that sends never receives, so two bases can never bounce the same load back and forth: for two-way supply, put a sending dock and a receiving dock at each end.
• The two slots on its terminal become an optional haul filter. Leave both empty and it hauls everything, except soldier scrolls, which stay behind as the escort's reserve.
• The wagon sets off once a stack's worth has piled up (freightMinItems), and never loads more than the destination chest has room for, so a delivery cannot spill onto the ground. Send now goes straight away.
• Same wagon, same escort, same roads and same theft protection as a trade caravan.

Barter with a safety guarantee

Trade is mirrored barter with escrow, built around one promise: you can only ever lose goods to your own wagon being raided. A partner's bad luck never costs you.

• Routes need mirrored offers: your "send 64 iron, want 10 diamonds" pairs with a partner's "send 10 diamonds, want 64 iron."
• Both halves are pulled into escrow before any wagon rolls; a failed run refunds the undelivered half.
• No partial shipments, ever. It ships the full agreed bundle or nothing.
• A surplus floor (64 of the exported item by default) always stays in the chest, so a trade only fires from genuine overflow and never drains your working stock to zero.
• Cross-player routes require a mutual whitelist, and links stay strictly pairwise. A player who owns both ends of a route enables "Trade with your own docks" instead.

Live two-convoy exchange

When both docks have a wagon ready, this is the main event:

• Both wagons roll out and meet at the midpoint of the route.
• They pull up side by side, the way real caravans park to hand off loot, pause for a visible cargo swap, then each carries its half home and deposits it in the partner's chest.
• If only one dock has a wagon, it falls back to a single round trip that fetches and delivers both halves itself.
• A hard anti-stuck failsafe watches every rig; if one ever wedges against terrain or the other wagon, it frees itself instead of freezing.

The Creative Dock: a shop that never runs dry

Trade between two players needs both of them online, stocked, and interested. A server shop needs none of that.

• A creative variant of the Caravan Dock that sells from endless stock, so a permanent server shop never needs restocking and never runs dry.
• It trades with everyone, with no mutual whitelist to arrange.
• The buyer chooses the size of their own order. The shop enforces a rate, not a fixed bundle: set "8 iron for 1 diamond" once and any multiple of it is accepted. Underpaying is refused, overpaying is allowed.
• Orders are capped to what one wagon can carry and are refused outright rather than part shipped, so the full bundle or nothing promise survives.
• It needs no wagon item, and a lost convoy is replaced on its own. Put a wagon in its slot only if you want a particular cart type.
• Soldier scrolls in its chest are templates: escorts are posted from them and topped back up after every run without a single scroll being used up.
• Without a chest beside it, it is a sink: payments and freight sent to it leave the world instead of piling up around the shop. Give it a chest to bank them instead. Its code doubles as a freight destination, so a server can run a collection point.
• Placed in creative or at operator level 2, and blast proof.

Bandits on the Road

A Creative Dock can be told to ship to nobody, and that is where the game is.

• Switch a Creative Dock to bandit mode and it ships on a timer to a paired Creative Endplate, with no partner and no payment, escorted by hostiles.
• The wagon is deliberately robbable. Players can intercept the convoy and take the cargo, so getting a shipment through is the escort's job rather than a formality.
• Escorts spawn properly armed, pillagers and vindicators by default. Drop spawn eggs in the dock's chest to set the band per dock, and each convoy rolls its own gear quality, so you can size up a shipment by how much of the escort is enchanted.
• Their equipment never drops, so an endless route is not a free gear farm.
• Dock and Endplate pair with a six character code and a copy button. A mistyped code is reported on the spot instead of failing silently.
• A convoy that reaches its Endplate vanishes: the shipment escaped.

A real wagon, driven and guarded

• An actual Trotting Wagons cart with two hitched draft horses and a seated Wagon Coach driver cracking a whip, cycling through five coach looks. The draft horses are invulnerable, so stray damage cannot strand a haul.
• With Hundred Years War installed, post soldiers as escorts just by dropping their unit scrolls in the linked chest, up to ten.
• Guards ride in formation around the wagon, break to fight threats, then reform. They cannot be marched off by a passing player, and friendly fire between your own caravan members is cancelled.
• A guard with a fight on its hands stops following and fights it, then falls back in when it is over. The convoy also watches for hostiles itself and hands them to any guard that has not noticed, so an escort in permanent catch-up is never whittled down without swinging back.
• A caravan under attack brakes and stands its ground until the fight is finished, which puts the whole escort back around the wagon instead of strung out along the road behind it. Time spent fighting is not charged against the journey.
• Shooting the driver brings the escort down on you, which is the one attacker a sweep for hostile mobs would never find.
• A non-owner who cracks open the wagon or its coach turns every posted guard hostile against them.
• Fallen escorts return as scrolls to your dock, and a returning wagon refills its detail from any scrolls waiting there.
• With Villager Recruits installed, your recruits can ride along too. Stand them near the dock and press Start Operation (or press it again while the wagon waits at home) and up to ten join the escort. They stay with the driver and fight whatever attacks the caravan, stragglers are brought back up to the wagon, and when the caravan is lost they stand down where they are and wait for you. Order one elsewhere and it simply leaves the escort.
• The armoured wagon is supported. It is the one wagon with no cargo bed of its own, so it carries freight in a sealed hold: the load cannot be seen or taken in transit, and getting at it means destroying the wagon.
• The royal wagon is barred by default as a passenger coach rather than a freight cart. It goes into the slot and is refused at Start Operation with a clear message, so the slot never looks broken. Set bannedWagons to change it.

Roads it actually respects

The wagon routes with a weighted search that thinks like a teamster:

• It hates hills, taking the flatter way around rather than scrambling straight over a rise.
• It prefers player-made roads: dirt paths and laid paving such as cobblestone, bricks, and planks read as safe road and pull the route onto them.
• With Via Romana installed, whatever Via Romana counts as a path block counts as road here too, so the roads you charted for yourself are the ones your wagons take, and drive faster on.
• On a wide road it hugs the crown down the middle instead of skating an edge.
• It never treats a lone stray block as a road, and the road preference can never lure it toward a hazard.
• Crossing water costs more than going around, so a bridge or a shoreline is taken whenever either exists and a wagon only wades when there is genuinely no dry route. Water is never made impassable, so an island dock stays reachable.
• The route home matches the route out. Climbing and descending are both charged, so a hill a caravan paid to detour around on the way out is not a free drop on the way back.

Tell it where the road is

• Bury a Caravan Checkpoint under your road and caravans come that way. Crafted from stone bricks and a compass, two at a time, and it works while buried and in unloaded chunks.
• A checkpoint only counts when it genuinely sits along the route. Anything outside the corridor between the two docks, or behind either end, is ignored, so a caravan never detours to one nowhere near where it is going.
• A long chain is sampled evenly along the route, so a road paved end to end with checkpoints keeps its shape instead of stopping at every single one.

Deep water

• Caravans that must cross deep water do it in style rather than trudging along the seabed. The draft team is swapped for skeleton horses, the driver changes to a drowned skin, and the escort is stowed for the crossing then restored on dry land with health, gear and identity intact.
• Detection uses water above and at the wagon, so fords and puddles never trigger it, and the driver does not drown.

Long hauls stay smooth: a travelling caravan carries a small chunk ticket so it keeps moving and pathing even with no player nearby, then lets those chunks unload once it parks.

Losing a wagon, and the dock grace period

• If a caravan is destroyed, the dock stands down and asks you to re-supply a wagon and press Start Operation again.
• If the dock block itself is broken while a caravan is out, a grace timer of about thirty seconds starts. Rebuild a dock in time and it re-homes the orphaned caravan, inheriting the old dock's offer, whitelist, and settings.
• Let the timer run out and the caravan goes derelict, its cargo left free for anyone to loot.
• Breaking a dock that still holds an un-launched wagon returns that wagon to you as an item.

Tuning

Every number lives in config/caravansconvoys-common.toml:

Supported versions

Mod ID caravansconvoys on both.

This mod ships no player-facing commands. Everything is driven from the dock terminal.

Support the Mods

These mods are free and they stay free. If one of them runs on your server, you can back the next version, the next port, and the next mod at patreon.com/epicwarborn. Patrons get their name in the credits, a direct line to me for bugs, early builds, and a vote on what gets built next.

Set the offer, start the operation, and watch the road do the work.

Part of The Warborn Realm, by barunn