> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lootroute.volvox.bot/llms.txt
> Use this file to discover all available pages before exploring further.

# Routes and data

> Route files, blacklists, whitelists, and the per-expansion node databases.

## On-disk roots

Defined in `Gatherer/Navigation.lua` (Windows paths, accessed through WGG's file API):

| Constant                        | Path                      | Contents                                         |
| ------------------------------- | ------------------------- | ------------------------------------------------ |
| `GATHERER_DATA_ROOT`            | `C:/WGG/scripts/Gatherer` | Bundled scripts and routes (`route/<name>.json`) |
| `GATHERER_PERSISTENT_DATA_ROOT` | `C:/WGG/GathererData`     | User-writable data (e.g. `Blacklist.json`)       |
| `GATHERER_DEFAULT_ROUTE`        | —                         | Core startup fallback: `"Daggerspine_Landing"`   |

`GATHERER_DEFAULT_ROUTE` is the bot-core startup fallback. `:LoadRoute()` with no selected `gatherer.route` falls back to the first scanned route or no route; the local `"default"` fallback is limited to save helpers such as `:SaveWaypoint()` / `:SaveRoute()`. Select a route explicitly before using route actions.

Routes and blacklists are plain JSON files.

## Routes

A route is a JSON file at `C:/WGG/scripts/Gatherer/route/<name>.json` — an ordered list of waypoints (position plus radius) the bot flies while scanning for nodes.

### Selecting a route

Pick a route in the settings UI (the dropdown is populated by `volvox.Gatherer:RefreshRoutes()`, which scans the route directory). The selection persists as `gatherer.route`; `:LoadRoute(routeName)` loads the JSON into the module and bot-core globals.

### Recording a route

<Steps>
  <Step title="Name it">
    Set `gatherer.new_route_name` and `gatherer.new_route_radius` (default `50`) in the settings UI. The name field saves when you press Enter or click away; route names are trimmed, cannot contain `/ \ : * ? " < > |`, cannot end with a period, and cannot be Windows reserved device names such as `CON`, `NUL`, `COM1`, or `LPT1`.
  </Step>

  <Step title="Record">
    Call **Start route recording** (`:StartRouteRecording()`), then fly your loop and add waypoints with **Add waypoint** (`:AddRouteWaypoint()`).
  </Step>

  <Step title="Save">
    **Save recorded route** (`:SaveRecordedRoute()`) writes `route/<name>.json`, verifies the file by reading it back, selects the new route, and loads it. Use `:StopRouteRecording()` to abandon a recording.
  </Step>
</Steps>

Use route recording for new or edited routes. Save failures are reported in chat, including an invalid name, missing waypoints, route-directory creation failure, or write verification failure. The legacy `:SaveWaypoint()` append helper does not rewrite a complete JSON document, so it is not the safe path for maintaining route files.

## Blacklists and whitelists

Two mechanisms keep the bot away from bad spots:

* **GUI position blacklist/whitelist** — `:BlacklistAdd()` / `:WhitelistAdd()` append the player's current position (with `gatherer.blacklist_radius` / `gatherer.whitelist_radius`) to `Blacklist.json` / `Whitelist.json` under `C:/WGG/scripts/Gatherer`.
* **Persistent automatic blacklist** — lower-level runtime helpers write automatic blacklist positions under `C:/WGG/GathererData`.
* **GUID blacklist** — `:BlacklistCurrentTargetGUID()` blacklists a specific node object by GUID.

The bot also maintains automatic, TTL-based runtime blacklists for failed gathers, depleted nodes, mob-blocked nodes, and inaccessible underground nodes — see the [configuration keys](/gatherer/configuration#node-filtering-and-blacklisting).

## Node databases

Static node data lives in `Gatherer/NodeData.lua`, sliced from `Data.lua`:

* **`KPNodeIDs`** — knowledge-point node IDs.
* **Per-expansion node databases** — tables named `VANIL` through `MID` (Vanilla through Midnight) mapping node GameObject IDs per expansion.
* **Area/traceline flag masks** used by node reachability checks.

## Rich Soil and Resilient Seeds

Rich Soil seed planting is part of the Midnight herbalism data in `Gatherer/Data.lua` and `Gatherer/GatherLogic.lua`:

* `GathererRichSoilIDs` contains Rich Soil (`524808`).
* `GathererResilientSeedItemIDs` contains the supported Resilient Seed item IDs (`237497`–`237500`).
* `GathererItemCount()` prefers `C_Item.GetItemCount` and falls back to legacy `GetItemCount` so Midnight clients without the global can still detect seeds.
* `GathererUseItemFromBags()` (in `Gatherer/Core.lua`) plants the seed by locating the item in the player's bags and using that exact container slot via `C_Container.UseContainerItem` — the same as the player right-clicking it in the backpack — falling back to use-by-ID only when the bag scan fails.
* When `gatherer.plant_resilient_seed` is enabled, the character has Herbalism, and a seed is available, Rich Soil bypasses ordinary node-ignore/gather-skip filters so `SEEDPLANT` can plant the seed and wait for the spawned herb.

New expansion nodes extend the relevant table in `NodeData.lua`. `volvox.Gatherer:ApplyExpansion(expansion)` points the active node database globals at the expansion tables.

<Note>
  Every numeric game ID (GameObject, item, spell, NPC) comes from [Wowhead](https://www.wowhead.com/) and is recorded in code with a comment naming the entity.
</Note>