# Homestead Farmhands 3.1.1

Homestead Farmhands adds a shared **Farmhand Lodge** which Robin can construct on
an owned QuantumFarm homestead. One lodge supports five independently hired
residents:

- **Farmer** — manages the assigned outdoor crop rectangle.
- **Rancher** — pets and feeds animals, opens animal doors, always succeeds at
  milking and shearing, gathers loose products, manages hay/grass, and services
  Slime Hutches.
- **Grower** — manages up to two greenhouse buildings plus fruit, moss, and
  tapper products from trees on the same homestead.
- **Gardener** — clears weeds, debris, and wild seedlings, repairs broken fences
  when matching fence items are in SUPPLIES, gathers homestead-only forage,
  services the homestead farm cave, and collects other produced homestead items.
- **Crabber** — gathers and rebaits the hiring player's valley crab pots and
  services every fish tank inside compact Aquarium buildings.

## Lodge and payroll

The left porch chest is **SUPPLIES**, the right porch chest is **HARVEST**, and
the exterior billboard manages the roster, assignments, work
reports, and payroll. The lodge is currently exterior-only and has no enterable
interior. When an older lodge is migrated, managed storage and any recoverable
contents are moved into the exterior SUPPLIES and HARVEST chests before the old
interior is retired.

There is no hiring fee or seasonal renewal. Each hired role costs **250g per
day** by default. At the start of the day the host pays roles in this stable
order: farmer, rancher, grower, gardener, crabber. A role which cannot be paid doesn't
work that day. The lodge bank holds at most **20,000g** and its balance is shown
over the lodge. A full five-person roster therefore costs 1,250g per day, or
35,000g for a 28-day season. Deposit 1,000g or 5,000g at a time through the
billboard. Wages and the cap are configurable.

HARVEST uses Big Stone Chest capacity and is automation-output-only. Place a
**Fjord Relay** beside it, interact with the device, choose **Sending**, point it at
HARVEST, and choose one of the eight color channels. In the farmhouse, place another
**Fjord Relay** beside a chest, choose **Receiving**, point it at that chest, and choose
the same color. The Receiving relay
fills that one chest until it is full. If the chest's green **OUT** button is
enabled, its contents are also available to the local Workbench/Fjord Pathway/machine network.
Device ownership keeps same-color multiplayer networks separate. Text Signs and
chest metadata do not create cross-location links in 2.0.
HARVEST remains output-only for players, so only farmhands can add to it.

Names are selected randomly from `NamePool` when a position is filled. Each role
has its own fixed, hatless design: Field Farmer, Stock Rancher, Greenhouse
Grower, Grounds Gardener, and Traditional Fisher. While rendered walking in the
world, every farmhand dynamically wears the homestead owner's currently equipped
hat. Changing the owner's hat changes the farmhands' hats without rehiring them.

Hiring and deposits immediately attempt to fund today's shift. A newly paid
worker appears and begins work during the current workday without waiting for
tomorrow.

## Work behavior

The farmer needs a hoe, watering can, seeds, and optional fertilizer in
SUPPLIES. Assign a rectangle through the farmer menu. Crop work runs in the
order harvest, clear dead crops, hoe, fertilize, plant, water. The farmer walks
between nearby harvests and carries up to `PickupBatchSize` crop stacks before
returning to HARVEST; the default is eight. Carried stacks are persisted on the
lodge so saving mid-trip doesn't lose or duplicate produce.

The rancher visits the farm and animal-building interiors, pets and feeds every
animal, opens coop and barn doors, and moves loose or tool-harvested animal
products into HARVEST. Milk-pail and shears work is direct and can't miss. Hay
is taken from SUPPLIES first, then silos, then edible pasture grass. The rancher
also fills Slime Hutch water troughs and gathers slime products.

All support roles rescan hourly during their paid workday, while each walking
route uses a stable snapshot so new work doesn't change a route already in
progress. The gardener collects ready processors, solar panels, lightning rods,
homestead-only forage, and homestead farm-cave output. Forage on the main farm
and elsewhere in the world is deliberately ignored. Broken fences are repaired
only when a matching fence item can be consumed from SUPPLIES. Normal/heavy
tappers, moss, and outdoor fruit-tree fruit belong to the grower. Aquarium
output belongs to the crabber. Machines on other homesteads are ignored. The
gardener doesn't remove grass, fruit trees, grown wild trees, or player-tagged
saplings.
Loose seeds dropped by wild trees are recognized through Stardew's loaded
`Data/WildTrees` registry and moved to HARVEST during that morning circuit,
including compatible content-pack seeds.
Untagged naturally spread wild trees are cleared through every immature growth
stage. Player-planted trees remain protected, and the legacy-tree protection
migration now runs only once instead of re-tagging wild growth after each load.
Version 2.1.5 conservatively snapshots every immature tree already present as
protected, fixing the earlier migration gap without risking established player
plantings. Trees which spread naturally after that snapshot remain unprotected
and are valid gardener work.
The snapshot and every gardener route are restricted to the connected visible,
walkable part of the dedicated homestead map containing the lodge. Empty map
canvas, blocked borders, and disconnected areas are ignored.

Crab pots require bait even when another modpack component grants Luremaster.
The crabber snapshots ready crab pots at the start of a host-authoritative daily
route through the default valley location context. Each round trip carries the
contents of at most two pots back to HARVEST. The worker calculates how many
complete walking routes fit into the remaining workday and reports daily capacity
as X of Y ready pots; overflow remains untouched for a later day. Ownership must
exactly match the homestead owner, so
multiplayer neighbors' pots are never touched. Island and desert contexts are
excluded. The crabber leaves each pot placed and consumes bait from SUPPLIES to
restock it after collection. If no bait is available, the emptied pot remains
unbaited. The crabber waits at the lodge if HARVEST is open or full. Pots remain
untouched until their catch can be deposited safely.
While a trip is active, the crabber is drawn walking on the loaded destination
map from its nearest known entrance to each pot's adjacent walkable shore tile,
then back toward a map exit. Stardew warp metadata supplies map entrances and
exits; disconnected custom maps fall back safely without blocking collection.

## Compact Aquariums

Robin's outdoor Fish Pond is replaced by an **Aquarium** building whose exterior
matches the current Slime Hutch footprint (7×4 in Stardew 1.6). Its interior
contains eight independent fish tanks. Each tank uses
Stardew's native animated fish-tank furniture, locked in place, so its actual
fish species swim behind the glass. The displayed fish are render-only and
can't be withdrawn or consumed through storage-aware mods. Each tank also uses
Stardew's native Fish Pond simulation for legal fish, population caps and gates,
spawn timing, requests, golden animal crackers, and produced rewards. Hold a
fish and interact with an empty tank to stock it; interact without a held item
to inspect its population and current request, or interact while holding a
fishing rod to remove one fish. The crabber deposits tank output
in HARVEST and fulfills requests from SUPPLIES.

The exterior glass shows clear water and stationary rock/coral scenery without
baked-in fish or flexible aquatic plants. Water shimmer and bubbles are drawn as
live effects, so the facade doesn't imply motion that the game can't animate.

On first load, existing outdoor Fish Pond buildings are consolidated eight at a
time into Aquarium buildings. Fish species, population, unlocked gates, spawn
progress, requests, crackers, and uncollected output are copied into interior
tanks. This migration intentionally changes the building footprint and is part
of the 3.0 breaking update.

Vanilla Auto-Grabbers are removed from shops. Existing placed Auto-Grabbers are
converted into ordinary storage chests while preserving their contents. The
separate AutoAnimalDoors and Torgo Auto Collector packages are retired in 2.0.
Their active Homestead work is owned by the rancher, grower, gardener, and
crabber roles; no inert legacy package or duplicate event handler remains.

Use the grower menu to bind the closest one or two greenhouse buildings on that
homestead. This is building-instance based for QuantumFarm multiplayer safety.
The grower harvests crops and fruit trees, clears dead crops, hoes diggable crop
tiles, fertilizes, plants ordinary seeds, plants fruit saplings only in the
isolated diggable wall slots authored into the IF2R and Frontier greenhouse maps,
recognizes every vanilla and content-pack fruit-tree sapling registered in
`Data/FruitTrees`, and waits at the lodge when required supplies run out. Once a
needed tool, crop seed, or fruit-tree sapling is placed in the SUPPLIES chest,
the grower automatically returns to the assigned greenhouse(s) and continues.
The grower remains on duty after a completed pass and rechecks both assigned
greenhouses every in-game hour, so later changes can create more work that same
day even when no missing-supply condition was detected.
It also waters planted crops. Connected diggable regions are crop beds; isolated
diggable tiles are tree-only slots. Supplies are consumed and all produce goes
to HARVEST.

If a required porch chest is open or full, work waits instead of bypassing the
multiplayer mutex or deleting items. A Relay in Sending mode never inserts into HARVEST;
SUPPLIES opts out of Fjord Automation input, output, and relays.

## Migration and diagnostics

An existing active 1.x seasonal contract is migrated to an indefinite farmer
position without another hiring charge. The current day's wage is taken during
load when the payroll bank can cover it, so the migrated farmer can resume work
immediately. Existing assigned crop areas and safely stored carried harvests
are preserved.

The host can use `farmhands_speed 1` through `farmhands_speed 10` for temporary
movement testing and `farmhands_status` for a detailed work/path/chest snapshot.
All world, item, money, roster, and report changes are host-authoritative.

For a full disposable-save integration run, load a brand-new Spring 1, Year 1
save and enter `farmhands_test setup confirm`. This deliberately advances the
test save to Spring 1, Year 2, unlocks its greenhouse, marks the main farm as a
test homestead, hires and funds all roles, and places a lodge, greenhouse, coop,
barn, Slime Hutch, animals, mixed-stage crops, fruit trees, debris, a wild and
player-protected seedling, ready tapper, lightning rod, solar panel, interior
processor, broken fence, pasture/hay fallback, homestead and cave forage, cave
mushroom box, legacy pond migration into an Aquarium with eight differently
stocked tanks, Aquarium output and request, retired Auto-Grabber, loose animal products, and two ready
crab pots. The first
phase intentionally omits seeds and fruit saplings. The suite waits until both
farmer and grower report the missing supplies and automatically restocks them.
After the morning fixtures pass, it creates a second wave of newly mature crops,
truffle, debris, tapper and machine products, fruit, Aquarium output, and crab-pot
catches, advances the clock by two hours, and verifies that every role reactivates
during the same day before printing the final report.
Use `farmhands_test restock` or `farmhands_test verify` to force either phase,
`farmhands_test status` for live worker and tank details, or
`farmhands_test aquarium` to warp directly inside the stocked Aquarium for
visual inspection. This command is
destructive and is intentionally refused on any save past Spring 1, Year 1.
The setup command first warps the host to the main farm, then clears the entire
disposable farm of objects, terrain features, resource clumps, debris, animals,
furniture, and nonessential buildings. The farmhouse, shipping bin, pet bowl,
and multiplayer cabins are retained. No manual farm clearing or prerequisite
setup is needed. Progression changes are committed only after
all fixtures are placed. If bootstrapping fails, partial test fixtures are
removed and the original date and unlock state are restored so setup can be
retried on the same disposable save.
After initialization succeeds, the host is warped to the clear tile directly in
front of the test lodge so the worker routes and nearby fixtures can be observed
immediately.

The temporary automatic gardener, farmer-task, and avatar-route diagnostics are
disabled. `farmhands_status` still prints current farmer, gardener, grower,
renderer, path, and chest state on demand, while unexpected errors remain logged.

Version 2.1.9 removes the blanket legacy marker which incorrectly protected all
immature trees in existing saves. Explicitly player-planted saplings retain their
`player` marker and remain protected. Farmer and grower seed selection now skips
seeds which the current location rejects, preventing an impossible planting task
from being selected repeatedly. Avatar movement consumes its full movement budget
across route waypoints so its visible arrival stays aligned with the work timer.

After the gardener completes the return trip—or has no morning work—the role
enters an off-duty `InsideLodge` state and its outdoor avatar is removed. The
state name is retained for save compatibility even though the lodge has no
enterable interior.

QuantumFarm greenhouse ownership is resolved from the lodge's parent homestead,
never from the global `Greenhouse` location name.
