Config Reference (Configuration)

Parent: Configuration Index | Home

This page is optional for players who want to tune behavior. If you only want to play, use the main guides instead.

For command-level guidance first, see:

• TW Settings for curated global world settings.
• TW Config for advanced family-by-family editor usage.

Full Tamework Config Docs

For complete field-by-field documentation across all config families, use:

• Alec's Tamework Config Reference Index

Bird flight formations

The aerial role templates expose these NPC role parameters. They are edited in role JSON, rather than through a Tw*Config asset.

Set these values in the species role's Modify map. Loose produces a compact group with gentle drift and staggered heights above and below the leader; Cluster produces a denser irregular group with gentle drift; Chevron produces two level arms behind the flock leader. Formation positions ease around turns. The formation flight controller caps turning at 90 degrees/second (or the configured limit if lower), including during landing and recovery. Wild formations retain separate slots during cruising and the leader's descent; followers switch to touchdown landing after the leader lands. Tamed formations apply during airborne idle. Both also keep flying in formation while alerted to a target that has not triggered fleeing; leaders and lone birds continue cruising. Close-threat fleeing and obstacle recovery take priority. Grounded birds retain their watch behavior, and individual commands keep their existing movement. Both require a flying flock leader and the matching Tamework build with flight formation support. Formation-enabled species have a lower minimum airspeed, allowing followers to catch up or slow down into position. Wild and tamed hawks and vultures enable IndependentFlightRoaming. During idle flight, leaders and followers share the leader's home leash point and choose independent waypoints around that home using IndependentFlightRoamRadiusRange (default [40, 70] blocks) and IndependentFlightRetargetTimeRange (default [10, 20] seconds). This takes priority over formation slots while retaining flock membership, normal flight pace, and obstacle avoidance. Other birds keep their configured formations. Leaders use the same roaming range and waypoint timing as followers; each bird chooses its own route around the shared home. Raptors gather around that home point specifically for Kettle episodes; alerts retain the existing Loose fallback. Follower catch-up leashes track the live leader, including on the ground. Independent roaming and Kettle read the leader's home directly, so home distance does not keep a nearby follower stuck in catch-up. Visual spacing and terrain behavior still need in-game tuning.

See Tamework's Flight Formation Guide for integration details.

Thermal circling (Kettle)

Wild and tamed hawks and vultures can enter daytime Kettle episodes during idle flight. Kettle uses a base pace of about 3.2 blocks/second on level flight, with each bird flying at 70-115% of that pace (capped at maximum flight speed). Hawks and vultures glide for 10.5 seconds, then flap for 1.5 seconds, with flock members offset so they do not all flap together. The leader circles around its home point. Nearby flock members begin joining after individual 2-20 second delays, using individual radii of 65-150% of the configured radius and distinct height bands across the configured altitude range. Members alternate clockwise and counterclockwise orbit directions, keeping their direction while membership is stable. Height differences persist for the whole episode instead of every bird eventually reaching the same ceiling. During the final 30 seconds, followers depart after individual 2-25 second delays and resume roaming; they cannot rejoin the same ending episode. The leader continues circling until the episode ends. Kettle beacon checks are non-consuming so landing, join-delay, and orbit checks can read the same signal. Landing, threat responses, recovery, and companion commands retain priority.

The aerial templates expose KettleEnabled (default false), KettleRelativeSpeed (default 0.8 of maximum flight speed), KettleRadius (default 18 blocks), KettleAltitudeRange (default [15, 28] above the leader's home point), KettleCooldownRange (default [120, 240] seconds of cooldown after an episode), and KettleDurationRange (default [180, 420] seconds).

The initial wait is 60-120 seconds. Later episodes last 3-7 minutes, with a 2-4 minute cooldown afterward. The cooldown is paused during circling and resumes when eligible idle flight next checks that the episode has ended. Wild birds defer their normal timed landing while a Kettle episode is running. Threats, recovery, nighttime, and companion commands can still interrupt an episode.

Wild bird flock sizes

Natural world spawns use species-specific weighted flock assets under Server/NPC/Flocks/AH_Flock_*.json. These ranges include the leader. Small and medium groups are more common than the largest groups; hawks have an 85% chance of spawning alone or as a pair. Terrain and spawn limits can produce fewer birds. Existing birds are not resized, and tamed group limits are unchanged.

These are game-scale choices informed by bird social behavior, not literal wild flock measurements. Social birds receive larger ranges, while solitary and pair-oriented birds receive smaller ranges. See Cornell's hawk flocking overview, raven life history, and San Diego Zoo's flamingo guide.

Archaeopteryx retains its parent-and-young spawning, Tetrabird retains 2-4, and Pterodactyl and Skrill retain singleton spawning. Bats are unchanged.

MinSize sets the first size and successive SizeWeights entries weight each next size. For example, MinSize: 1 with SizeWeights: [55, 30, 10, 5] means 55% one bird, 30% two, 10% three, and 5% four. Natural spawn overrides change only the selected bird entries' Flock references; other spawn settings retain their release 0.6.3 values. Mods overriding the same world spawn assets may conflict with these assignments.

Active Animal Husbandry Config Files

These are the current (non-deprecated) AH* config assets in this repo.

Core Family Files

Command Item Icon Options

Each command item config can list icon choices for players to assign to individual flutes. Each State must match a key in that item asset's top-level State map, where the state overrides the icon. The LabelKey identifies a translated option name.

"IconOptions": [
  { "State": "RedCircle", "LabelKey": "server.items.AnimalHusbandry_Command_Item.icon.redCircle" }
]

The list can contain any number of options. Animal Husbandry currently provides eight color-and-shape choices for each flute. Add a matching state icon to each flute item asset and translations for every supported locale when adding choices.

Group Mapping (including Beast)

Harvest-capable livestock configs cover chicken, cow, mosshorn, sheep, and skrill families. General livestock configs cover livestock families without harvest interactions, so they do not roll Bounty traits or spend points on harvest-only talents.

Deprecated Naming Note

Older Tw*Config_AnimalHusbandry_* asset ids/names are deprecated and were replaced by the AH* config file set above.

Safety Tips Before Editing Configs

1. Make a backup of the file.
2. Change one section at a time.
3. Restart and verify startup logs.
4. Test one species before broad rollout.

Fast Tuning Targets

• Too much breeding: raise BaseCooldownMinutes.

• Too little breeding: lower cooldown and improve care quality.

• Growth too slow/fast: tune TimeToFullGrownMinutes per role.

• Adult aging: tune Aging.AdultToPrimeMinutes, PrimeMinutes, and SeniorMinutes in the breeding profiles or their exact-role RoleOverrides. These use eligible real minutes. NonPrimeYieldMultiplier defaults to 0.5 in Animal Husbandry. Lifecycle mode and old-age death are controlled through /tw settings.

• Leveling too slow/fast: tune BaseXp, GrowthFactor, and each XpSources section.

• Talents too strong/weak: tune TalentPoints and the multipliers in the active AHTalent config.

• Overcrowding: lower MaxNearbySameType on sensitive species.

Pigeon_Boid is an experimental spawnable pigeon variant using local Boid steering instead of Cluster slots. Its flock membership is restricted to other Pigeon_Boid birds; natural pigeon spawns remain unchanged.