> For the complete documentation index, see [llms.txt](https://machina-1.gitbook.io/machina-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://machina-1.gitbook.io/machina-docs/llamas/configuration.md).

# Configuration

A commented `config.yml` is generated on first run and works at its defaults. Apply any change live with **`/caravan reload`** — no restart.

## Storage runs — `storage-run` & `out-of-view`

| Key                                 | Default | What it does                                                             |
| ----------------------------------- | ------- | ------------------------------------------------------------------------ |
| `storage-run.return-min-seconds`    | `10`    | Return time when your nearest depot is close.                            |
| `storage-run.return-max-seconds`    | `90`    | Return time (the cap) when the depot is far.                             |
| `storage-run.return-near-distance`  | `24`    | At/under this distance the run takes the minimum time.                   |
| `storage-run.return-far-distance`   | `256`   | At/over this distance the run takes the maximum; linear between the two. |
| `storage-run.stuck-timeout-seconds` | `15`    | If a courier can't get clear, it vanishes anyway after this.             |
| `storage-run.depart-min-distance`   | `8`     | Blocks a llama must visibly walk away before it may slip out of sight.   |
| `out-of-view.near`                  | `8`     | Within this range a llama is always considered visible.                  |
| `out-of-view.far`                   | `32`    | Beyond this it's always considered gone.                                 |
| `out-of-view.fov-degrees`           | `70`    | Half-angle of your forward view cone (behind it = not seen).             |

### Automatic runs — `storage-run.auto`

| Key                    | Default | What it does                                                         |
| ---------------------- | ------- | -------------------------------------------------------------------- |
| `enabled`              | `true`  | Let a full following caravan dispatch its own run.                   |
| `threshold-percent`    | `80`    | Send a run once this % of the caravan's storage slots are used.      |
| `cooldown-seconds`     | `60`    | Minimum gap between auto-runs for a player.                          |
| `full-backoff-seconds` | `300`   | Longer wait after a run came back with leftovers (depots were full). |

## Saddlebags & leveling — `storage` & `progression`

| Key                             | Default | What it does                                                                                |
| ------------------------------- | ------- | ------------------------------------------------------------------------------------------- |
| `storage.pages`                 | `6`     | 15-slot pages per maxed llama (6 × 15 = 90 slots). Set `1` for vanilla — no extra pages.    |
| `progression.minutes-per-level` | `60`    | Minutes of playtime to earn one strength level (+3 slots), up to 5. `0` turns leveling off. |

## The follow feel — `steering`

The elastic-band follow and the believable movement live here. The knobs you're most likely to touch:

| Key                      | Default | What it does                                                                |
| ------------------------ | ------- | --------------------------------------------------------------------------- |
| `max-speed`              | `0.22`  | Cruising walk speed (blocks/tick).                                          |
| `comfort-radius`         | `10`    | Inside this gap a follower just cruises — no catch-up boost.                |
| `boost-after-seconds`    | `3`     | Time outside the band before it rubberbands to catch up.                    |
| `teleport-after-seconds` | `30`    | Time outside the band before it teleports in (a dip back inside resets it). |
| `catchup-max-speed`      | `0.32`  | Top catch-up speed (\~1.5× walking).                                        |
| `teleport-distance`      | `48`    | Hard cap — past this (≈3 chunks) it teleports immediately.                  |
| `return-distance`        | `24`    | How far behind you a teleported llama reappears, then walks in.             |

{% hint style="info" %}
The same section holds the swim controller (`water-*`), hazard look-ahead (`hazard-lookahead`, `cliff-drop`), step hop (`jump-velocity`), and the anti-circling escape (`turn-rate-degrees`, `oscillation-threshold`, `escape-commit-seconds`). The defaults are tuned — adjust only if you want a different feel.
{% endhint %}

## Caravan — `caravan`

| Key              | Default | What it does                                             |
| ---------------- | ------- | -------------------------------------------------------- |
| `range`          | `12`    | How far the tools look for your chest-llamas.            |
| `look-range`     | `6`     | Max distance to a container you're recording as a depot. |
| `follow-spacing` | `2.5`   | Blocks between llamas in the line.                       |

## The lead camel — `quartermaster`

| Key                    | Default | What it does                                                          |
| ---------------------- | ------- | --------------------------------------------------------------------- |
| `enabled`              | `true`  | Turn the camel quartermaster role on or off.                          |
| `minutes-per-tier`     | `90`    | Minutes of playtime to earn one quartermaster tier. `0` turns it off. |
| `max-tier`             | `5`     | The tier ceiling.                                                     |
| `run-speedup-per-tier` | `8`     | % faster storage-run return per tier (tier 5 × 8% = 40% off).         |

See [The lead camel](/machina-docs/llamas/the-lead-camel.md).

## Guardians & protectors — `guard` & `protector`

See [Guardians](/machina-docs/llamas/guardians.md) for the guardian-llama table (`guard.radius`, `spit-damage`, `slow-seconds`, `cooldown-seconds`, `knockback`). The wolf protector's reach is `protector.radius` (default `16`).

## Admin commands

Players use the Drover's Stick and Khipu — but a `/caravan` command exists as an admin/fallback:

`/caravan <follow | stay | guard | store | home | status | give | reload>` · `reload` and `give` need `caravans.admin`.

***

*Caravans is built by* [***Machina***](https://wearemachina.com) *— custom Minecraft plugins and more at* [*wearemachina.com*](https://wearemachina.com)*.*


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://machina-1.gitbook.io/machina-docs/llamas/configuration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.