fs25-adsmartpickup/docs/USER_MANUAL.md

# AD Smart Pickup — user manual

Version 1.17.6 · Farming Simulator 25 · add-on for AutoDrive

*Dansk version: [BRUGERMANUAL.md](BRUGERMANUAL.md)*

AD Smart Pickup makes your AutoDrive tractors think for themselves. You say what should go where,
and the mod decides trip by trip which good to fetch, from which silo, and where to unload it.
Everything is set up in one place in the ESC menu, and all tractors in a flow start and stop together.

The mod does two things:

- **Supply (into building):** keeps barns and factories filled. Each trip, the tractor fetches the
  good the target needs most, from a silo anywhere on the map.
- **Delivery (out of building):** empties factories, silos, barns and pallet sheds. Goods are taken
  to storage or sold when the price is close to the yearly top.

---

## Contents

1. [Requirements and installation](#1-requirements-and-installation)
2. [Key concepts](#2-key-concepts)
3. [Prepare the map: markers and Wait points](#3-prepare-the-map-markers-and-wait-points)
4. [The Smart Pickup menu](#4-the-smart-pickup-menu)
5. [Supply: keep barns and factories filled](#5-supply-keep-barns-and-factories-filled)
6. [Delivery: empty, store and sell](#6-delivery-empty-store-and-sell)
7. [Tractors and trailers](#7-tractors-and-trailers)
8. [Start, stop and saving](#8-start-stop-and-saving)
9. [The storage tabs: inventory and statistics](#9-the-storage-tabs-inventory-and-statistics)
10. [Recipes](#10-recipes)
11. [Troubleshooting](#11-troubleshooting)
12. [Glossary](#12-glossary)

---

## 1. Requirements and installation

**Required**

- **FS25_AutoDrive.** The mod builds on AutoDrive's Pickup & Deliver and does not change AutoDrive.
- An **AutoDrive road network** connecting silos, barns, factories, selling points and Wait points.

**Recommended**

- **Universal Autoload (UAL)** on trailers that should carry pallets. Without UAL the mod can only
  move bulk goods such as grain, milk, silage and TMR.

**Installation**

1. Put `FS25_ADSmartPickup.zip` in the mods folder:
   `Documents/My Games/FarmingSimulator2025/mods/`
2. Enable the mod together with AutoDrive when you choose your savegame.
3. The AutoDrive setting **"Use folders"** must be allowed on. The mod switches it on when a flow
   starts. The setting is global, so it applies to the whole game.

---

## 2. Key concepts

**Flow.** A flow is a named recipe. It has a direction, buildings, goods, rules and a list of
tractors. Older versions called it a *run*, and the word is still used on some buttons.

**Building.** A barn, factory, silo, object storage (pallet shed) or selling point. You pick
buildings, not markers. The mod finds the AutoDrive marker that belongs to the building's trigger.

**Marker.** An AutoDrive destination. Every building needs a marker within 40 m of its loading or
unloading trigger. A barn often has several, such as one at the milk tank and one at the slurry tank.

**Wait point.** A marker in an AutoDrive folder with the word **Wait** in its name. Tractors park
here while they wait for space, for a good price or for demand. Wait points are one shared pool for
all tractors.

**Need.** How much of a good a barn or factory is missing. For factories it is measured as *time
until empty*: the good that runs out first is fetched first.

**Reserve.** What the farm's own barns and factories will use during the next day. The reserve is
never sold.

---

## 3. Prepare the map: markers and Wait points

### Markers at the buildings

Place an AutoDrive marker where the **tractor's nose** stops when the trailer is in the trigger.
The marker must be at most **40 m** from the building's trigger.

- **Silos in tight rows:** the mod picks the silo whose trigger is *behind* the tractor's nose in
  the driving direction. This stops the neighbouring silo from getting the load.
- **Barns with several loading points:** give each point its own marker, such as *Cow 1 Milk* and
  *Cow 1 Slurry*. The mod shows all of them next to the barn.
- **Object storages (pallet sheds):** place the marker so the trailer's autoload zone covers the
  storage's output area, just like when you load by hand.
- **Marker names:** names are free. The menu shows the building's own name and the marker's name.

### Wait points

1. Create an AutoDrive folder with **Wait** in its name, such as *Cow Wait* or *Wait*.
2. Put as many markers in the folder as you have room for. One per tractor is plenty.
3. Connect every Wait point to the road network **in both directions**, from the buildings and back.

Wait markers are never used as a source or target, even when they stand close to a building.
Markers in field folders, such as *F91 Wait*, are left alone, because it is the **folder** name
that counts.

### Tight silos and AutoDrive's trigger distance

AutoDrive tips at the first unloading trigger within its global **"Max trigger distance"**, which is
25 m by default. If your silos stand closer than that, the neighbouring silo can get the load. Set
the option to **10 m** in that case. The mod writes a warning to the log the first time it sees a
storage target with a neighbouring trigger.

---

## 4. The Smart Pickup menu

Press **ESC** and open the **Smart Pickup** tab. It has five sub-tabs:

| Tab | Contents |
|---|---|
| **Flows** | The board with all flows, editing of the selected flow and the Wait pools |
| **Factories** | Inventory and statistics for the farm's factories |
| **Silos** | Inventory and statistics for the farm's silos |
| **Barns** | Inventory and statistics for the farm's barns |
| **Pallet sheds** | Inventory and statistics for the farm's object storages |

### The flow board

At the top there is one line per flow. The selected flow is marked with `>`.

```
> Milk sale: Milk · Cow Barn 1 + Cow Barn 2 → Sell · price >= 90 %, storage > 80 % · Virtus · Running (1/1)
  Barn feed: by need · all silos → Cow Barn 1 · need · JCB 1 + JCB 2 · Stopped (2 tractors)
```

Read the line as **name: goods · from → to · rule · tractors · status**.

- A `!` after a building name means the building has no marker.
- `!!` in the status is a warning, such as a selling point that cannot be reached.
- The status also says why a tractor is waiting, such as `SUGAR 78 % of top (needs 90)`.

### Buttons

| Button | What it does |
|---|---|
| **New run** | Creates a new flow. It starts as *Into building* |
| **Rename** | Renames the selected flow |
| **Delete run** | Deletes the flow and stops its running tractors. Cannot be undone |
| **Start run / Stop run** | Starts or stops all tractors in the flow |

Pick a flow in the **Run** field at the top. The details of the selected flow are shown below the board.

### Direction

The **Direction** field switches between two kinds of flow:

- **Into building** is supply. See [section 5](#5-supply-keep-barns-and-factories-filled).
- **Out of building** is delivery. See [section 6](#6-delivery-empty-store-and-sell).

### The building list

Each building is shown on one line with its markers and their distance to the trigger:

```
Cow Barn (large) — Cow 1 Milk 6 m · Cow 1 Slurry 4 m
Silo 7 (silo) — NO MARKER within 40 m — place an AD marker at the trigger
```

Set **Yes** on the buildings the flow should use. The list is sorted by name, so *Silo 9* comes
before *Silo 10*. A building you have sold shows as *building no longer exists*.

---

## 5. Supply: keep barns and factories filled

A supply flow keeps one or more buildings filled with everything they use.

### Setup

1. **New run**, and leave Direction on **Into building**.
2. Under **To**: set Yes on the barns and factories to fill.
3. Under **Goods**: choose **Auto** or **Select**.
   - **Auto** fetches everything the building accepts. For factories, that is the inputs of the
     productions that are switched on.
   - **Select** lets you tick specific goods.
4. Set **Loops**, **Return from Wait below** and **Wait pool**. See the rules below.
5. Set **Yes** on the tractors that should drive.
6. Press **Start run**.

**From** always shows *all silos*. The tractor fetches from any silo on the map.

### How each trip is chosen

Before each loading, the mod looks at the targets and picks:

1. **The neediest good.** For factories, that is the good that runs out first. For barns, it is the
   lowest fill level compared with capacity.
2. **Full loads first.** Goods where a whole load fits come before goods where only part fits.
3. **The barn that needs it most.** With several targets, the neediest one gets the trip.
4. **Which silo.** Your own silos are used before borrowing from neighbours. The least-filled silo
   is emptied first, so leftovers get cleared. Milk, slurry and digestate are taken from the
   *fullest* source, so production never stops.

A factory's own **inputs** are never taken from the factory itself. Straw in a TMR factory stays
where it is.

**Factories follow their productions.** Switch TMR on in a factory, and the tractor starts fetching
silage, hay, straw and mineral feed by itself. Switch it off, and the tractor stops. Productions
the map switched off because an input ran out still count as wanted, because those are exactly the
ones that need filling.

### Best feed first

Feed in a barn trough shares space. If better feed such as **TMR** is on the list, lower feed such
as silage and hay is only fetched when the trough is **at least 75 % empty**. That way silage does
not fill the trough while TMR is available.

### Several tractors on the same barn

The mod remembers what is already **on the way** to each barn. With four trailers on the same barn
they spread out. One fetches TMR, another straw, and a third drives to the next barn, instead of all
of them fetching the same thing.

### Leftover loads and Wait

When the target cannot take the whole load, this happens:

1. The tractor unloads what fits.
2. The rest is taken to the **nearest free Wait point**, so the trigger is not blocked for the next
   tractors.
3. It drives back when the target can take **the whole rest**, or has dropped below **Return from
   Wait below**.

A rest of less than 100 l that the target cannot take counts as empty. The tractor drives on instead
of blocking the trigger.

### Load swap

When a tractor waits with a good the target is full of, while the target needs another good on the
list, it swaps loads:

1. The rest is unloaded in an ordinary storage silo that accepts the good and has room.
2. The tractor then fetches the good the target is missing.

This only happens when the target is missing at least a quarter of its capacity of the other good,
and there is a road to the silo and on to the target. With no suitable silo, the tractor stays at Wait.

### Supply rules

| Rule | Meaning | Values |
|---|---|---|
| **Loops** | Number of trips per tractor before it parks | 0 = endless, otherwise 1–99 |
| **Return from Wait below** | A waiting tractor returns when the target is below this fill level | 10–90 %, default 50 % |
| **Wait pool** | Which Wait folder the tractors wait in | *All (nearest free)* or a folder |

Below the rules, **To fetch** lists the goods the flow is fetching now, neediest first.

---

## 6. Delivery: empty, store and sell

A delivery flow takes goods out of buildings and drives them to storage or to a selling point.

### Sources

Under **From** you can pick:

| Source | What is taken |
|---|---|
| **Factory** | The factory's outputs, both bulk and pallets from the pallet spawner |
| **Silo** | The silo's contents |
| **Barn** | Milk, slurry and manure from the barn's loading points, including attached extension tanks such as Milk Tank Extension |
| **Object storage** | Pallets and bales. They are taken out one at a time |

**Sources with shared storage:** some storages are extensions that share their stock with everything
within a set distance, such as a row of milk tanks. Loading at one empties them all. The mod detects
this and treats them as one stop, so the tractor does not drive between the tanks. The first one in
the list is used, and the log says which sources were merged. Choosing a single tank as the source
is enough.

### Policy per good

Every good in the sources is listed with its amount and current price. Pick a policy:

| Policy | Meaning |
|---|---|
| **Off** | The good is left alone |
| **Store** | Taken to a silo, a pallet shed or one of the farm's own factories that uses the good, such as slurry for a biogas plant. This happens when there is a full load, or the source is nearly full |
| **Sell** | Sold when the price is close enough to the yearly top |
| **Sell, else store** | Sold at a good price. Otherwise taken to storage when the source is nearly full |

Bulk goods need a tipper or tank. Pallet goods need a trailer with Universal Autoload.

### Delivery rules

| Rule | Meaning | Values |
|---|---|---|
| **Sell from** | Goods are sold when the price is at least this share of the yearly top price | 50–100 %, default 90 % |
| **Drive to storage above** | Store goods are moved when the source is filled above this share | 50–95 %, default 80 % |
| **Collect in one trip** | Collection round, see below | Yes/No |

### How each trip is chosen

Before each loading, and every five seconds while the tractor waits, the mod checks:

1. **Sell.** If a Sell good's best *reachable* selling point pays at least the threshold, the tractor
   drives to sell **regardless of amount**. This makes sure you get the money when the price peaks.
   The highest price share goes first.
2. **Store.** If a Store good has a full load, or a source is above its threshold, it is taken to the
   nearest silo with room for the whole load. The fullest source goes first. Markers another delivery
   flow loads from are only used for unloading when nothing else fits. That way a storage trip does
   not unload where a sale trip needs to load.
3. **No trip.** The tractor parks at a Wait point and tries again. The status says why, such as
   `holding at Wait 3: SUGAR 78 % of top (needs 90), storage 41 %`.

### The price

Selling points are the map's real selling points and factories the farm does not own, such as the
map's dairy. Deliveries to the farm's own factories and barns do not count as sales. The price share
is the good's current price compared with the yearly high. The mod uses the same
seasonal curve as the game's price graph. Goods with a flat curve always count as 100 %. The selling
point with the best price wins, as long as the road network reaches it.

### Reserve: never sell what the farm needs

Before selling, the mod subtracts what the farm's own factories and barns will use during the next
day. It only sells when a whole load can be taken without touching the reserve. The status shows,
for example, `SUGARBEET: 196.0k reserved for TMR factory`. The Store policy does not touch the
reserve, because the good stays on the farm.

### Collection round

With **Collect in one trip** switched on:

- **Tipper:** the same good is collected from several sources until the trailer is full. The next
  source is only visited when at least 10 % of the space is left.
- **Autoload trailer:** several pallet goods with the same destination go on one trip.

### Pallets and Universal Autoload

- The mod switches AutoDrive's **AL unload** on for the trailer when the flow starts.
- **Straps** are tightened after loading and released **25 m before** the unloading trigger.
- A full load of pallets is at least four pallets.
- Pallets for storage go to the nearest pallet shed that accepts the good and has room.
- From an object storage, pallets are taken out **one at a time**, so none are left on the ground.
- If the storage gets stuck, loading ends after 30 seconds with what is on board. If an autoload
  source makes no progress for 15 seconds, the tractor leaves with what it has.

### On-screen warnings

When a selling point cannot be reached, or no silo has room, the mod shows a red AutoDrive message,
for example:

```
'MT635' cannot reach selling point 'Grain Elevator' for SUGAR – check the road network
```

The message also goes to AutoDrive's message history, to `log.txt` and to the flow's status. The
tractor waits at Wait and drives by itself once the road is connected. The warning is only repeated
when the tractor, station or good changes.

---

## 7. Tractors and trailers

At the bottom of the flow, the farm's vehicles are listed with their capacity. Set **Yes** on the
ones that should drive.

- Capacity is shown in litres for bulk trailers and as *autoload (pallets)* for UAL trailers.
- **Vehicles that cannot be used are locked** and show the reason. The reasons are in the table.
- A vehicle can only be in one flow. If it is moved, it shows *moved from 'other flow'*.
- If you remove a running tractor from a flow, it is stopped.
- **Names:** tractors automatically get an AutoDrive driver name after their flow, such as
  *Milk Collect 1* and *Milk Collect 2*. A tractor that is alone in its flow gets the flow's name.
  The name is used in AutoDrive, in the menu and in the log, and the menu shows the model name in
  brackets. When a tractor leaves its flow, it gets its model name back. Names you set yourself in
  AutoDrive are only changed while the tractor is in a flow.

| Reason | Meaning |
|---|---|
| no trailer | The tractor has no trailer attached |
| trailer cannot carry the run's goods | The trailer accepts none of the flow's goods |
| pallet goods need Universal Autoload on the trailer | The flow has pallets, but the trailer has no UAL |
| too far from the road network | The tractor is too far from AutoDrive's network |
| no target / no recognised source | The flow has no buildings |
| no good selected | A delivery flow with no good set to Store or Sell |
| no Wait point in the pool | Delivery needs at least one Wait point |

---

## 8. Start, stop and saving

**Start run** does this on every approved tractor:

- Puts AutoDrive in **Pickup & Deliver** with the flow's goods and loops.
- Switches **Use folders** on globally and sets rotation to **loading only**.
- Sets the flow's markers. They are picked again for every trip.

This **overwrites** the tractor's own AutoDrive settings. Tractors outside flows drive as before.

A flow starts even if one of the chosen buildings has no marker. The status then names the
building. If **none** of the buildings has a marker, start is refused with `'<building>' has no AD
marker at its trigger`.

**Stop run** stops AutoDrive on the flow's tractors. The tractors stay in the flow, so it can be
started again.

**Saving.** Flows are saved in `savegameN/ADSmartPickup_runs.xml` when the game is saved, and on
every Start and Stop. After loading, tractors that AutoDrive saved as running carry on. Tractors that
were waiting at a Wait point resume waiting by themselves. If a flow is stopped after loading, press
**Start run** again.

Flows from older versions load automatically. Old marker choices are translated into buildings.

---

## 9. The storage tabs: inventory and statistics

The **Factories**, **Silos**, **Barns** and **Pallet sheds** tabs each show one type of building.
They work the same way. Figures update every second, and each tab remembers the building you picked last.

### Statistics for a building

Pick a building in **Show building**. Below the selector there is a table with column headings and
one row per good:

| Item | In building | Value now | At top price | Farm | Lasts | Use/prod. per day |
|---|---|---|---|---|---|---|
| Silage | 483.5k/935.5k 52 % | € 173,921 | € 193,400 | 1.7M | 34.0 days | -50.0k |
| Milk | 1.3k/10.3M 0 % | no selling point | | 233.1k | - | +14.4k |
| **Building total** | | € 425,885 | € 429,039 | | | |

| Column | Meaning |
|---|---|
| **In building** | Amount and capacity in the selected building, plus fill level |
| **Value now** | The value at the best price right now, across all selling points on the map |
| **At top price** | The value if you sell at the year's highest price |
| **Farm** | The farm's total amount of the good across all buildings, including those on the other tabs |
| **Lasts** | How many days the farm's stock lasts at use minus production. *rising* means the farm produces at least as much as it uses |
| **Use/prod. per day** | Daily use with a minus sign and daily production with a plus sign |

At the bottom, **Building total** shows the building's total value now and at top price.

### Overview of the tab's buildings

Below the statistics, the tab's buildings with contents are shown as a grid. The building name is on
the left, with up to two goods per row. Factory outputs are marked with `*`, and pallet sheds show the
number of pallets.

**What is counted**

- **Factories:** use and production of the productions that are running right now. Factories that
  are idle or missing inputs are not counted.
- **Barns, use:** feed, straw and water. Water is not counted when the barn has automatic water.
  Feed use is split across the feed types in the trough.
- **Barns, production:** each animal's output by age times the number of animals. This covers milk,
  buffalo milk, manure, slurry, eggs, wool and goat milk. Young animals below production age do not count.

Goods the farm does not use show a dash under **Lasts**. Goods with no selling point show *no
selling point*.

---

## 10. Recipes

### Keep a cow barn fed

1. Wait folder *Cow Wait* with 2–4 markers close to the barn.
2. New flow, **Into building**, To = the barn, Goods = **Auto**.
3. Wait pool = *Cow Wait*, Loops = 0.
4. Two tractors with tippers, Yes, Start.

The tractors share feed, straw and water by need and pick TMR over silage.

### A TMR factory feeding several barns

1. Flow A: **Into building**, To = the TMR factory, Goods = Auto. The tractor fetches what the
   switched-on productions are missing.
2. Flow B: **Out of building**, From = the TMR factory, TMR = **Store**. TMR goes to a silo.
3. Flow C: **Into building**, To = all cow barns. The neediest barn gets the trip.

### Sell milk at a high price

1. New flow, **Out of building**, From = barn(s) or milk tanks.
2. Milk = **Sell, else store**, Sell from = 90 %, Drive to storage above = 80 %.
3. One tanker, Yes, Start.

The tanker waits at Wait until the price is high. If the tank fills up first, the milk goes to storage.

### Empty a pallet shed for sale

1. New flow, **Out of building**, From = the object storage.
2. Goods = **Sell**, **Collect in one trip** = Yes.
3. One UAL truck, Yes, Start.

---

## 11. Troubleshooting

The mod writes every decision to `log.txt` with the prefix `ADSmartPickup:`. The log is in
`Documents/My Games/FarmingSimulator2025/`.

| Problem | Fix |
|---|---|
| The building shows *NO MARKER* | Place an AutoDrive marker within 40 m of the trigger. Wait markers do not count |
| A barn's slurry or milk point is missing | The points are often at opposite ends of the barn. Give each point its own marker |
| The tractor is locked in the list | Read the reason next to it in [section 7](#7-tractors-and-trailers) |
| The tractor just sits at Wait | Read the status. It is usually waiting for price, space or demand |
| The neighbouring silo gets the load | Set AutoDrive's *Max trigger distance* to 10 m |
| *cannot reach selling point* | Connect the selling point to the network in both directions |
| The pallet shed does not hand out pallets | Move the marker so the trailer's autoload zone covers the output |
| Pallets fall off | Check that the trailer has UAL. Straps are tightened after loading |
| The tractor does not fill at the silo | After 30 seconds without filling, the mod lets go and AutoDrive drives on |
| The flow does not run after loading | Press **Start run** again |
| All tractors fetch the same good | Check that they are in the same flow. Only tractors in one flow share the work |

The log lines are written in Danish. Typical examples:

```
ADSmartPickup: 'JCB 1' bytter læs: 2400 l STRAW tilbage i Silo 3, målet mangler FORAGE
ADSmartPickup: 'Virtus' holder ved Wait 3: MILK 82 % af top (kræver 90), lager 41 %
ADSmartPickup: 'Fastrac' genoptager ventning ved Cow Wait efter genindlæsning
```

These mean: a load swap, a tractor holding for a better price, and a tractor resuming its wait
after the savegame was loaded.

---

## 12. Glossary

| Term | Meaning |
|---|---|
| **AD** | AutoDrive |
| **Flow / run** | A named recipe with buildings, goods, rules and tractors |
| **Marker** | AutoDrive destination at a building |
| **Trigger** | The area at a building where goods are loaded or unloaded |
| **Wait point** | A marker in a folder with *Wait* in its name, where tractors wait |
| **UAL** | Universal Autoload, a mod that loads pallets automatically |
| **Object storage** | Pallet and bale storage, such as the one in the HVF pack |
| **Top price** | The good's highest price during the year according to the game's seasonal curve |
| **Reserve** | What the farm's own barns and factories use during the next day |
| **Time until empty** | How long a factory's stock of a good lasts at the current use |