Skip to content

Configuration

Townstead splits configuration between server-side behaviour and client-side preferences. Server settings control villager AI, needs, work, storage, calendar behaviour, and integrations. Client settings control local settings: audio, catalog UI, the dialogue screen, and accessibility options.

Tables are grouped by configuration section, such as [needs.hunger], with the setting names shown as they appear inside that section.

[needs.hunger]
enableVillagerHunger = false
[storage]
respectProtectedStorage = true
protectedStorageBlocks = ["minecraft:barrel"]
protectedStorageTags = ["townstead:protected_food_storage"]
[calendar]
agingScale = 16.0

agingScale sets how many Minecraft days equal one year of villager age. Higher values make everyone age more slowly.

[roots]
blockedSpecies = ["townstead_roots:webster"]
blockedRoots = ["townstead_roots:moon_elf"]

Blocked roots disappear from the root picker and stop spawning naturally. See Roots for the full rules.

Server settings affect world behaviour. On a dedicated server, the server’s values decide how villagers behave.

[needs.hunger]

Hunger controls whether villagers get hungry, where they look for food, and what clean up they do after eating.

SettingDefaultValuesDescription
enableVillagerHungertruetrue, falseEnables villager hunger. When disabled, villagers skip hunger decay, eating behaviours, and hunger-driven mood drift.
enableSelfInventoryEatingtruetrue, falseAllows villagers to eat food from their own inventory.
enableGroundItemSourcingtruetrue, falseAllows villagers to collect food from ground items.
enableContainerSourcingtruetrue, falseAllows villagers to pull food from containers and item handlers.
enableCropSourcingfalsetrue, falseAllows villagers to harvest mature crops for food as an emergency fallback. Disabled by default to save crops and help with performance.
preferServedFoodtruetrue, falseRanks plated meals and other served food alongside chests and dropped items, with a bonus, so a nearby laid table beats a far pantry. When false, villagers eat served food only when no stored or dropped food is reachable.
enableChorusFruitTeleporttruetrue, falseLets villagers teleport when they eat chorus fruit, just like players do.
enableEmptyContainerDropofftruetrue, falseLets villagers store empty bowls, bottles, and buckets in nearby storage after eating or drinking. Skipped while actively working so tools are not taken mid-task.

Thirst settings are only applied when a supported thirst mod is installed. Supported backends are Thirst Was Taken, Thirst Was Reclaimed, Legendary Survival Overhaul, and Tough As Nails.

[needs.thirst]
SettingDefaultValuesDescription
enableVillagerThirsttruetrue, falseEnables villager thirst when a thirst backend mod is installed.
enableSelfInventoryDrinkingtruetrue, falseAllows villagers to drink thirst-restoring items from their own inventory.
enableGroundItemThirstSourcingtruetrue, falseAllows villagers to collect thirst-restoring items from ground items.
enableContainerThirstSourcingtruetrue, falseAllows villagers to pull thirst-restoring items from containers and item handlers.
enableCropThirstSourcingfalsetrue, falseAllows villagers to harvest mature crops for thirst-restoring food or drink as an emergency fallback. Disabled by default to save crops and help with performance.
thirstLethalFallbackfalsetrue, falseAllows dehydration to kill villagers. (NOT CURRENTLY WORKING)
enableCookWaterPurificationtruetrue, falseAllows cook villagers to purify impure water bottles in available kitchen skillets.
preferKitchenStorageForEmptyBottlestruetrue, falseWhen villagers drink from bottles, prefers depositing empty bottles into kitchen storage.
preferredBackend"auto""auto", "legendary_survival_overhaul", "thirst", "tough_as_nails"Which thirst mod drives villager thirst when more than one is installed. auto prefers Legendary Survival Overhaul, then Thirst Was Reclaimed or Thirst Was Taken, then Tough As Nails. Pinning a backend falls back to that order if the pinned mod is not installed. thirst covers both Thirst Was Taken and Thirst Was Reclaimed, since they share a mod id and cannot be installed together.

Fatigue controls how villagers accumulate exhaustion during activity and recover through rest.

[needs.fatigue]
SettingDefaultValuesDescription
enableVillagerFatiguetruetrue, falseEnables villager fatigue.
enableFatigueAlertstruetrue, falseShows local chat alerts when villagers collapse from exhaustion or recover.
fatigueNocturnalMultiplier0.75NumberFatigue accumulation multiplier when working during aligned cycle hours.
fatigueMisalignedMultiplier1.25NumberFatigue accumulation multiplier when working during misaligned cycle hours.
[needs.temperature]
SettingDefaultValuesDescription
enableVillagerTemperaturetruetrue, falseEnables temperature: body temperature for villagers and players, room heat, crop climate, and the Room Thermometer and Thermostat. Villagers drift toward the climate at their position, dress for it, and seek a hearth or shade when they are uncomfortable. Temperature also needs Legendary Survival Overhaul, Cold Sweat or Tough As Nails.
preferredBackend"auto""auto", "legendary_survival_overhaul", "cold_sweat", "tough_as_nails", "builtin"Which mod reports the ambient temperature. auto uses the first installed mod of Legendary Survival Overhaul, Cold Sweat and Tough As Nails. builtin uses only Townstead’s own model, but a temperature mod must still be installed.
climateAuthority"townstead""townstead", "backend"Whose climate counts when a temperature mod is installed. townstead sets the mod’s outdoor temperature from Townstead’s climate model. backend keeps the mod’s own climate and adds only what it lacks. See Temperature Mods.
[conversations]
SettingDefaultValuesDescription
enabledtruetrue, falseAllows villagers to start conversations on their own, including during hangouts. Operator previews still work when this is off.
idleStartChance0.30.0 to 1.0Chance, on each idle check about every ten seconds, that a villager invites a nearby available villager to talk. Hangout and Pheno conversations use their own timing.
[cannibalism]

Who may eat meat from people, which is any item in the townstead:cannibal_meats tag. Each tier includes the ones below it.

SettingDefaultValuesDescription
modeOFFOFF, PREDATORS, TRAIT, EVERYONEOFF: nobody. PREDATORS: roots that eat sapients may eat other kinds, never their own. TRAIT: predators as above, and villagers with the cannibal trait may eat anything. EVERYONE: anything goes. At TRAIT and above, a villager who slides into starvation has a very small chance of acquiring the trait.
producefalsetrue, falseOffers and works sapient meat at worksites: order sheets list it and eligible jobs may process it.

These settings apply to every profession, including professions added by data packs. Profession feedback JSON still decides what a villager can say and may request a longer interval; the server configuration supplies the universal policy and the shortest permitted interval.

[feedback]
SettingDefaultValuesDescription
enableWorkFeedbacktruetrue, falseAllows villagers to speak about their work, including one-time events and repeated requests.
enableRepeatedWorkRequeststruetrue, falseAllows villagers to repeat requests when missing supplies, tools, targets, or worksites block their work. One-time work events remain enabled.
minimumRequestIntervalTicks3600200 to 24000Sets the minimum ticks between repeated work-feedback messages from one villager. A profession may use a longer interval in its feedback JSON.

Farming settings control farm radius, targeting cadence, water placement, and grooming.

[farming]
SettingDefaultValuesDescription
enableFarmAssisttruetrue, falseEnables lightweight farming assist: anti-trample and idle unstuck nudges for harvest chores.
farmerFarmRadius124 to 32Maximum horizontal farm radius around the anchor used by farmer AI.
farmerCellCooldownTicks1200 to 2400Minimum ticks before reworking the same soil cell.
farmerPathfailMaxRetries31 to 20How many times a target can fail pathing before it is temporarily blacklisted.
farmerIdleBackoffTicks600 to 1200Ticks to wait before reacquiring work after no valid target is found.
enableFarmerWaterPlacementtruetrue, falseAllows farmers to place water sources in cells painted Water in the plot planner.
farmerWaterSourceSearchRadius728 to 192Maximum horizontal distance farmers may travel to find water for bucket refills.
farmerWaterSourceVerticalRadius82 to 32Vertical search radius for nearby water sources when refilling buckets.
farmerGroomRadius10 to 4Radius around planned farm cells where farmers may clear removable weeds.
farmerGroomScanIntervalTicks6020 to 1200Ticks between farmer grooming target scans.
[fishing]
SettingDefaultValuesDescription
fishermanWaterSearchRadius164 to 48How many blocks away from the barrel to look for water when fishing.
fishermanInventoryFullThreshold161 to 64Number of items the fisherman carries before returning to deposit.

These settings are general policy seams for data-authored work. A Job may consult one of them without adding a Profession- or mod-specific section to Townstead’s configuration.

[professionWork]
SettingDefaultValuesDescription
allowLethalWorktruetrue, falseAllows data-authored villager Jobs that deliberately kill a living target.
lethalWorkCooldownTicks2400200 to 24000Default minimum time between lethal work actions by one villager.
processTrophyOutputsfalsetrue, falseAllows authored Jobs to process rare display-worthy outputs rather than preserve them.
[caregiving]
SettingDefaultValuesDescription
enableFeedingYoungtruetrue, falseAllows adults to feed hungry babies, toddlers, and children.
enableHydratingYoungtruetrue, falseAllows adults to bring drinks to thirsty babies, toddlers, and children. Only appears when thirst backend is active.
enableNonParentCaregiverstruetrue, falseAllows non-parent villagers to help feed children when parents are absent.

Storage settings decide whether villagers automate supply movement and which containers are off-limits.

[storage]
SettingDefaultValuesDescription
enableWorkSupplyAutomationfalsetrue, falseAllows chore supply restocking and output storage automation from nearby containers.
enableHarvestOutputStoragetruetrue, falseAllows harvesting villagers to store gathered output in nearby containers.
respectProtectedStoragetruetrue, falseWhen true, villagers will not take food from protected storage blocks or tags.
protectedStorageBlocks[]List of block IDsBlock IDs that villagers must not take food from.
protectedStorageTags["townstead:protected_food_storage"]List of block tag IDsBlock tags treated as protected storage.

Use full resource IDs for protected storage entries:

[storage]
protectedStorageBlocks = ["minecraft:barrel", "minecraft:chest"]
protectedStorageTags = ["townstead:protected_food_storage"]

Roots settings let a server disable specific identity content without editing data packs. Each list takes resource ids. A root is blocked when its own id is listed, or when the species, ancestry, or lineage it resolves through is listed.

[roots]
SettingDefaultValuesDescription
blockedRoots[]List of root idsRoots to disable on this server.
blockedSpecies[]List of species idsBlocks every root that resolves to a listed species.
blockedAncestries[]List of ancestry idsBlocks every root whose ancestry is listed, whether the root declares the ancestry directly or reaches it through its lineage.
blockedLineages[]List of lineage idsBlocks every root that selects a listed lineage.

Blocking does three things:

  1. Blocked roots are hidden from the root picker, for both players and the villager editor.
  2. Blocked roots are never rolled for naturally spawned villagers, including as part of a mixed-ancestry founder.
  3. The server rejects any attempt to apply a blocked root, so clients cannot bypass the picker.

Blocking is not retroactive. Villagers and players that already carry a blocked root keep it, keep their appearance, and can still pass it to children. Blocking only stops new selection and new natural spawns.

Id entries follow two conveniences:

  • Entries without a namespace assume townstead_roots, so "moon_elf" means "townstead_roots:moon_elf".
  • Legacy townstead_origins ids are accepted and treated as the matching townstead_roots id.
[roots]
blockedRoots = ["townstead_roots:moon_elf"]
blockedSpecies = ["townstead_roots:webster"]
blockedAncestries = []
blockedLineages = []

This example removes the Moon Elf root and every Webster root from the picker and from natural spawns, while other elves stay available.

Calendar settings control profile selection, offline time behaviour, aging, and new-world start dates.

[calendar]
SettingDefaultValuesDescription
profile"auto"auto or profile IDActive calendar profile. Use auto to detect seasonal mods, or pin a profile ID such as townstead_calendar:default, townstead_calendar:serene, townstead_calendar:tfc, or townstead_calendar:ecliptic.
realClockCalendarfalsetrue, falseWhen true, the calendar also advances by the real-world days that elapsed while the game was off. When false, it tracks Minecraft days only. Compatible with day-cycle mods either way.
agingScale8.00.01 to 100000.0Minecraft days per villager age year. Raise it to slow all aging; lower it to speed all aging.
disableVillagerAgingfalsetrue, falseWhen true, villagers hold their current life stage and apparent age, and away-time age catch-up is skipped. Animals still grow normally while loaded.
randomizeStarttruetrue, falseApplies only to new worlds. Rolls a random starting year and day-of-year when the world is freshly created.
startYearMin15000 to 100000Applies only to new worlds. Lower bound for the rolled starting display year.
startYearMax22000 to 100000Applies only to new worlds. Upper bound for the rolled starting display year. If this is less than or equal to the minimum, only the minimum is used.

When realClockCalendar is false, Townstead follows Minecraft’s day counter. Use this for vanilla pacing or with day-cycle mods that already control the length of a Minecraft day.

When realClockCalendar is true, Townstead also adds the real-world days that elapsed while the game was off when the world loads again. Use it for long-haul life-sim worlds where the calendar should keep moving while you are away.

Settings for Personas and for villagers who are downed instead of dying. The Switchboard Personas dial also sets permadeath.

[personas]
SettingDefaultValuesDescription
permadeathfalsetrue, falseWhen false, a Persona who would die is downed instead and gets up later. When true, Personas die like anyone else.
downedRecovery"DAWN"MINUTES, DAWN, DAYHow long a downed villager stays down when nobody helps. MINUTES: about five minutes. DAWN: until the next dawn, and at least half a day. DAY: a full day.

This section appears when Chef’s Delight is installed.

[chefsdelight_compat]
SettingDefaultValuesDescription
enableTownsteadCooktruetrue, falseWhen enabled, Townstead handles cook AI and profession assignment. When disabled, Chef’s Delight handles cooking instead.

Debug settings are useful while testing behaviour, but are usually noisy in regular play.

[debug]
SettingDefaultValuesDescription
debugVillagerAIfalsetrue, falseEnables debug chat messages for villager AI, including farmer and cook behaviour.
debugVillagerSleepfalsetrue, falseEnables sleep and rest debug logs and villager debug state updates.
debugLoggingfalsetrue, falseEnables verbose diagnostic logs in several systems. For example, every line of a villager conversation goes to the log.

Client settings affect only the local player’s presentation and UI.

[needs_display]
SettingDefaultValuesDescription
temperatureUnitCELSIUSCELSIUS, FAHRENHEITUnit for temperature readouts in tooltips and on the thermometer.
[mood_audio]
SettingDefaultValuesDescription
muteMoodVocalizationstruetrue, falseMutes villager mood vocalizations tied to laughter, celebration, and crying.
[catalog]
SettingDefaultValuesDescription
useTownsteadCatalogtruetrue, falseUses the Townstead extended catalog with kitchen building tiers. Disable to use MCA’s original catalog.
[dialogue]
SettingDefaultValuesDescription
useRpgDialoguetruetrue, falseShows the Townstead visual overlay on MCA’s talk screen. Set to false to use MCA’s default talk screen.

With useRpgDialogue set to false, MCA’s Talk button opens MCA’s default talk screen, and so does the Talk to Villager key. The setting is local to the player, so two players on one server can each use the talk screen they prefer.

See Conversations & Dialogue.

The resource HUD has its own focused settings screen with a live preview and reset button. It is a sub-screen of Townstead’s client configuration rather than a replacement for the mod configuration screen, and is available on both supported 1.20.1 and 1.21.1 builds. These settings are local to the player.

[resource_hud]
SettingDefaultValuesDescription
anchorPACK_DECIDEDSix screen anchors or PACK_DECIDEDOverrides every meter’s datapack anchor. PACK_DECIDED honours each resource separately.
offsetX4-4096 to 4096Horizontal pixels from the selected anchor before HUD scale.
offsetY4-4096 to 4096Vertical pixels from the selected anchor before HUD scale.
scale1.00.5 to 3.0Additional meter scale on top of Minecraft’s GUI scale.
stackDOWNDOWN, RIGHTDirection used when several meters share an anchor.
visibilityCONTEXTUALCONTEXTUAL, NOT_AT_REST, ALWAYS, NEVERGlobal presentation rule for meters the datapack allows.
exitStyleFADEINSTANT, FADE, SLIDE, FLICKERTransition used when a contextual meter leaves. INSTANT disables the transition; ALWAYS visibility prevents disappearance entirely.
holdTicks600 to 1200How long a contextual meter remains fully visible after a value or definition change.
fadeTicks100 to 200Duration of the selected exit transition after the hold time.
showValuestruetrue, falseShows the current and maximum values beside meters.

NOT_AT_REST keeps a meter visible while its value differs from the resource’s authored start value. Otherwise it uses the same contextual hold and exit transition. The ability wheel temporarily keeps meters visible regardless of this choice.

SLIDE fades while moving toward the nearest top or bottom edge. FLICKER disappears in increasingly sparse flashes. Reduce Motion turns either of those into a plain fade. The settings screen repeats the selected exit treatment in its live preview.

The settings screen uses a practical -256 to 256 range for the offset sliders. The wider file range is retained for unusual display layouts.

Datapack authors control a meter’s shape, frame, effects, recommended anchor, and eligibility. Players retain final control over placement, scale, labels, and whether eligible meters are shown. See Resource HUD.

[accessibility]
SettingDefaultValuesDescription
reduceMotionfalsetrue, falseReduces non-essential motion across Townstead UI, including dialogue text effects, the calendar stamp drawer slide, and similar effects. Emotion colours still apply.
disableParticlesfalsetrue, falseDisables screen-space and world-space particles during dialogue.
disableCameraMovementfalsetrue, falsePrevents the camera from rotating to face the villager during dialogue.
spiritColorblindPatternsfalsetrue, falseAdds distinct hatching patterns to Spirit page bars so they can be told apart without colour.
spiritNarrationfalsetrue, falseAnnounces the hovered spirit row through the narrator.
spiritLargerHitTargetsfalsetrue, falseGrows Spirit page row heights and bar thickness for easier clicking on touch or low-precision setups.
spiritHighContrastfalsetrue, falseUses stronger borders and pure black/white text on the Spirit page.
spiritFontScale1.01.0 to 2.0Text scale multiplier for the Spirit page. Respects Minecraft’s overall GUI scale.

Use this list when you already know the setting name and just need to find its section.

SettingConfig Category
enableVillagerHunger[needs.hunger]
enableSelfInventoryEating[needs.hunger]
enableGroundItemSourcing[needs.hunger]
enableContainerSourcing[needs.hunger]
enableCropSourcing[needs.hunger]
preferServedFood[needs.hunger]
enableChorusFruitTeleport[needs.hunger]
enableEmptyContainerDropoff[needs.hunger]
enableVillagerThirst[needs.thirst]
enableSelfInventoryDrinking[needs.thirst]
enableGroundItemThirstSourcing[needs.thirst]
enableContainerThirstSourcing[needs.thirst]
enableCropThirstSourcing[needs.thirst]
thirstLethalFallback[needs.thirst]
enableVillagerTemperature[needs.temperature]
preferredBackend[needs.temperature]
enabled[conversations]
idleStartChance[conversations]
mode[cannibalism]
produce[cannibalism]
enableCookWaterPurification[needs.thirst]
preferKitchenStorageForEmptyBottles[needs.thirst]
preferredBackend[needs.thirst]
enableVillagerFatigue[needs.fatigue]
enableFatigueAlerts[needs.fatigue]
fatigueNocturnalMultiplier[needs.fatigue]
fatigueMisalignedMultiplier[needs.fatigue]
enableWorkFeedback[feedback]
enableRepeatedWorkRequests[feedback]
minimumRequestIntervalTicks[feedback]
enableFarmAssist[farming]
farmerFarmRadius[farming]
farmerCellCooldownTicks[farming]
farmerPathfailMaxRetries[farming]
farmerIdleBackoffTicks[farming]
enableFarmerWaterPlacement[farming]
farmerWaterSourceSearchRadius[farming]
farmerWaterSourceVerticalRadius[farming]
farmerGroomRadius[farming]
farmerGroomScanIntervalTicks[farming]
fishermanWaterSearchRadius[fishing]
fishermanInventoryFullThreshold[fishing]
allowLethalWork[professionWork]
lethalWorkCooldownTicks[professionWork]
processTrophyOutputs[professionWork]
enableFeedingYoung[caregiving]
enableHydratingYoung[caregiving]
enableNonParentCaregivers[caregiving]
enableWorkSupplyAutomation[storage]
enableHarvestOutputStorage[storage]
respectProtectedStorage[storage]
protectedStorageBlocks[storage]
protectedStorageTags[storage]
blockedRoots[roots]
blockedSpecies[roots]
blockedAncestries[roots]
blockedLineages[roots]
profile[calendar]
realClockCalendar[calendar]
agingScale[calendar]
disableVillagerAging[calendar]
randomizeStart[calendar]
startYearMin[calendar]
startYearMax[calendar]
enableTownsteadCook[chefsdelight_compat]
debugVillagerAI[debug]
debugVillagerSleep[debug]
muteMoodVocalizations[mood_audio]
useTownsteadCatalog[catalog]
useRpgDialogue[dialogue]
anchor[resource_hud]
offsetX[resource_hud]
offsetY[resource_hud]
scale[resource_hud]
stack[resource_hud]
visibility[resource_hud]
exitStyle[resource_hud]
holdTicks[resource_hud]
fadeTicks[resource_hud]
showValues[resource_hud]
reduceMotion[accessibility]
disableParticles[accessibility]
disableCameraMovement[accessibility]
spiritColorblindPatterns[accessibility]
spiritNarration[accessibility]
spiritLargerHitTargets[accessibility]
spiritHighContrast[accessibility]
spiritFontScale[accessibility]
permadeath[personas]
downedRecovery[personas]