Caravans

Caravans

Caravans puts moving, defended targets on your map. Every so often a horse-drawn
merchant wagon sets out across the world with an armed escort walking beside it. It follows a real
route, it fights back, and if you manage to bring it down it spills a chest of cargo whose value you
will not know until you open it.

Built for Minecraft 1.20.1 (Forge) and aimed at medieval and roleplay servers, where
a caravan raid gives players a reason to leave base and a reason to fight each other over the road.

How a raid plays out

1. The server rolls a random interval — roughly an hour on default settings — and a caravan departs.
2. Every player gets a chat announcement, with the departure coordinates if the server allows it.
3. The wagon walks its route at a loaded-cart pace, two draught horses in the traces, two to four
   soldiers marching alongside.
4. You attack. The entire escort turns on you at once — hitting the wagon, a guard, or even
   one of the horses is enough.
5. Fight past them and break the wagon. A chest drops where it falls, its cargo graded
   Poor, Average or Perfect.
6. Leave it alone and the caravan reaches its destination and disappears. The cargo is gone.

The wagon

• A custom covered wagon model, roughly 2.4 blocks wide and 3 blocks tall, with a draught pole out
  front and four wheels that turn as it travels.
• Walks a real waypoint route using ground pathfinding, with stuck detection so a wagon that jams
  against terrain steers itself free instead of standing still forever.
• Tough but not invincible: health, armour and speed are all configurable (150 HP by default).
• Two draught horses are pinned to the yoke. They take no damage themselves — hitting a
  horse is treated as hitting the wagon, so you cannot cripple a caravan by picking off the
  animals.

The escort

Guards are not decoration. They are configured by entity id, so you can escort your caravans with
whatever soldier entity your modpack already has.

• They retaliate, together. Damage the wagon, a guard or a horse and the attacker is
  handed to every guard in the caravan immediately.
• They stay with the cargo. Guards only fight within a leash radius of the wagon
  (24 blocks by default). Run far enough and they break off and return — you cannot pull the escort
  away and then double back for a free wagon.
• No friendly fire. Members of the same caravan cannot damage each other, so a stray
  arrow in a melee never turns the escort on itself.
• Periodic recall. Every three minutes any guard that has drifted too far is brought
  back beside the wagon, so terrain can never strand an escort.
• Kitted out. Guards spawn in full diamond armour and carry rations. Armour does not
  drop by default — a few full diamond sets per caravan would be worth more than the cargo — but that
  is one config line away.
• By default they are not hostile on sight. They are guards, not bandits. There is a
  config switch if you want them to be.

Recruits support (optional)

Caravans works out of the box with the Recruits mod, and the default guard list uses
Recruits soldiers: recruit, recruit_shieldman, bowman and
crossbowman.

There is no hard dependency. Guard entities are looked up from registry ids at runtime,
so Caravans installs and runs on its own — it simply falls back to a configured vanilla entity when the
ids are not present. Want to escort caravans with something else entirely? Put its id in the config.
Not sure what the id is? Run /caravan probe <modid> in game and the mod prints every
entity that mod registered.

Cargo

When a wagon dies, a chest is placed at the wreck with its loot table still unrolled — the contents are
generated the moment a player opens it, so nobody can peek before the fight is over.

All three are ordinary datapack loot tables
(caravans:chests/wagon_poor, wagon_average, wagon_perfect).
Drop a file with the same path into your world’s datapack folder and you have rewritten the entire cargo
economy without touching the mod. The odds themselves are weights in the config.

Plan the roads yourself

Left alone, the mod generates a curving route through open terrain near your players. But if you have
built roads, you probably want caravans to use them.

The Caravan Wand lets you walk your road and lay the route down by hand:

Then /caravan route save <name>. Saved routes live in the world save and survive
restarts. You can drop waypoints as far apart as you like — the mod re-samples the line and snaps it to
the ground before a wagon uses it, which is what keeps vanilla pathfinding from giving up on a waypoint
four hundred blocks away.

/caravan route show <name> draws the finished path in particles so you can walk it
and check your work.

Commands

All commands require permission level 2 (operator).

Configuration

Everything lives in config/caravans-common.toml, grouped and commented. Some of what you
can change:

• Spawning — interval range, how many caravans may be on the road at once, how far
  from players they appear, which dimensions they use.
• Routes — prefer saved routes or always generate, generated route length, waypoint
  spacing, arrival tolerance.
• Wagon — health, armour, speed, lifetime, whether draught animals spawn and which
  entity they use.
• Guards — the entity id pool and fallback, how many spawn, follow and leash
  distances, the recall interval, friendly fire, hostile-on-sight, cleanup delay.
• Guard equipment — each armour slot by item id, armour drop chance, ration item and
  stack size.
• Loot — the weight of each cargo grade.
• Notifications — departure, arrival and destruction messages, and whether departure
  coordinates are revealed.

Requirements

• Minecraft 1.20.1
• Forge 47+
• Install on both the server and the client — the mod adds a custom entity and its renderer.
• Recruits is optional. Install it for soldier escorts; without it the escort falls
  back to the configured vanilla entity.

Language support

English and Turkish are included. Every message, item and entity name goes through the language file,
so additional translations only need a resource pack.

Notes

• The wagon is a wide entity and needs a two-block-wide, three-block-high corridor to walk through.
  Dense forest and steep terrain will slow a caravan down; open ground and built roads look best.
• Caravans that never reach their destination are cleaned up automatically, and the escort is removed
  shortly after a wagon is destroyed, so nothing accumulates on a long-running server.
• Forge does not rewrite an existing config file when defaults change. After updating, either delete
  caravans-common.toml to regenerate it or check the changed keys by hand — newly added
  keys are appended automatically.