v2.2.0

2.2.0 - Progression, Coop Integration, and UI/Behavior Refinements - 2026-03-07

Added

• Foundation breeding and traits asset types: TwBreedingConfig and TwTraitConfig, including role-priority resolution and default example assets.
• Foundation shared happiness asset type: TwHappinessConfig, including role-priority resolution and default example assets.
• Foundation needs asset type: TwNeedsConfig, including role-priority resolution and default hunger/thirst config under Server/Tamework/Needs.
• New coop integration asset type: TwCoopConfig under Server/Tamework/Farming/Coops, keyed by CoopId with priority-aware selection and parent fallback support.
• New progression components: TameworkBreedingComponent and TameworkTraitsComponent, plus bootstrap initialization for newly tamed companions.
• New shared progression component: TameworkHappinessComponent with config id, value, and last-update timestamp.
• New shared progression component: TameworkNeedsComponent with hunger/thirst values, passive-sweep tracking, and applied happiness penalty state.
• New progression component: TameworkAttachmentsComponent for persisted model attachment selections used by offspring appearance inheritance.
• Progression persistence bridges for spawner capture/spawn and command-linked death/respawn snapshots (breeding + traits fields).
• Initial Breed interaction handling for happiness-gated readiness state setup.
• Unit tests for breeding/traits priority resolution and trait-value metadata codec round-trips.
• Deterministic trait assignment service (TraitRollService) with duplicate/conflict enforcement and seed-based rolls.
• Trait modifier resolver service (TraitModifierService) for effect-key multiplier lookups from rolled trait values.
• Unit tests for trait roll determinism/conflict handling and trait modifier multiplier resolution.
• /tw gethappiness command to inspect targeted NPC happiness source/value and breeding eligibility context.
• /tw getneeds command to inspect targeted NPC hunger/thirst state, applied needs penalty, and needs timing/config context.
• /tw setneeds <hunger> <thirst>, /tw sethunger <value>, and /tw setthirst <value> debug commands for direct in-game needs tuning on targeted NPCs.
• /tw sethappiness <value> and /tw gettraits commands for in-game progression debugging and balancing.
• /tw settraits <TraitId> <Value> [TraitId Value ...] and /tw addtrait <TraitId> <Value> debug commands for explicit trait assignment on targeted NPCs.
• /tw setbreedingready [true|false|toggle] debug command to force/clear breeding readiness on the targeted NPC (including cooldown clear when forcing ready).
• New life-stage progression component/service (TameworkLifeStageComponent, CompanionLifeStageService) plus /tw getlifestage debugging command.
• /tw findnpc <uuid> [mark:on|off] command to resolve a specific NPC by UUID, print live world state, and optionally mark its location with particles.
• Unit tests covering trait inheritance blending/mutation bounds and life-stage transition/scale interpolation behavior.

Changed

• Plugin bootstrapping now registers breeding/traits asset stores and component codecs.
• Coop capture-crate intake now supports optional Tamework policy overlays when a matching TwCoopConfig exists, while still using vanilla coop admission gates (tryPutResident) for resident-capacity/species acceptance parity.
• Interaction/docs coverage updated to reflect current breeding behavior (no longer a pure stub path).
• Interaction requirement buckets now support PlayerHandEmpty for explicit empty-hand gating.
• Interaction Requires.Parameter matching now evaluates all resolved role scopes (role/global/exec/sensor fallback) instead of only a single scope, fixing false negatives for valid params such as boolean flags.
• Trait bootstrap now backfills empty trait components with deterministic rolls and role-config IDs.
• Feeding interactions now apply shared happiness gains from happiness config (or shared defaults when no happiness config resolves), including trait-based HappinessGainMultiplier scaling.
• Feeding interactions now also apply manual needs refill (hunger, plus optional thirst for configured water-bucket items), while the new CompanionNeedsSystem handles periodic hunger/thirst decay, passive container feed, passive water drinking, and needs-driven happiness penalties.
• Needs progression now supports sensor-driven resource seeking: low-thirst companions can target adjacent drink positions near water, low-hunger companions can target adjacent eat positions near food containers using role FoodItemIDs, and Component_Tamework_Instruction_Needs_Seek_Resource now enters seek states through needs/resource sensors rather than hook triggers.
• Needs passive refill and needs-resource seek scans now support configurable vertical search depth via PassiveRefill.ContainerVerticalScanRadius and PassiveRefill.WaterVerticalScanRadius.
• Breeding config resolution now supports direct config-id lookup (resolveById) and shared resolver usage across breeding/spawner/respawn paths.
• Happiness updates now route through shared CompanionHappinessService (with BreedingHappinessService retained as a compatibility shim), keeping architecture open for non-breeding consumers.
• Equilibrium happiness modifiers now support population bands (Modifiers.Population) with configurable nearby same-type radius and count ranges, enabling lonely/social/crowded offsets.
• Disposition (HappinessGainMultiplier) now scales all happiness deltas and equilibrium modifiers: positive contributions scale directly by disposition, while negative contributions are inversely scaled so high disposition softens detractors and low disposition amplifies them.
• Spawner metadata and command death/respawn snapshots now persist shared happiness state and restore breeding happiness from that shared source for backward-compatible migration.
• Breed interaction eligibility now evaluates effective fertility using trait key FertilityMultiplier plus optional interaction FertilityBonus before readiness is set.
• Breed interaction eligibility now enforces TwBreedingConfig.Eligibility.RequireNotSleeping and RequireNotInCombat state gates in addition to tame checks.
• TwInteractionConfig_Example now includes a crouch-gated owner Breed entry for Mob_Tamework_Example so breeding readiness can be tested in-game.
• Breeding now performs nearby partner matching and applies a staged sequence (parent approach movement -> hearts particles -> delayed offspring spawn).
• Breeding parent approach now prefers role-driven pair movement via Tamework.Breeding.Pair.Start + BreedPair state hooks, with proximity-gated hearts/spawn and fallback direct move for roles without pair-state support.
• Breeding pair movement now keeps parents in pair state briefly after arrival (about 1s) before resetting, and offspring spawn delay after hearts is slightly longer for clearer pacing.
• Breeding hearts trigger sooner after pair arrival by using faster proximity checks and a less strict pairing-ready distance threshold.
• Offspring spawning now supports role baby-variant selection with fallback juvenile scaling, trait inheritance via TraitInheritanceService, and alarm-backed parent/offspring breeding cooldown locks.
• Breeding inheritance now supports deterministic random attachment inheritance with weighted parent/random selection and mutation (TwBreedingConfig.Inheritance.AttachmentInheritance), and offspring attachment selections now persist and reapply across runtime role/model transitions.
• Breeding cooldown and offspring lifecycle growth durations now use game-time timestamps with configurable conversion basis (TwBreedingConfig.Timing.Basis), while remaining authored in human-readable seconds.
• Adult breeding gates now use explicit life-stage progression when present (with role-name fallback), and life-stage state now persists through spawner capture/spawn and command death/respawn snapshots.
• Breeding offspring spawn now retries nearby fallback positions and uses additional role-resolution fallbacks to prevent silent no-spawn outcomes after successful pairing/hearts.
• Breed interaction custom effects now apply only when breeding actually starts, preventing false-positive "ready" feedback when blocked (for example by cooldown).
• /tw gethappiness now reports breeding cooldown state (cooldownActive, cooldownRemainingMs, cooldownUntilMs) and readyNow to clarify readiness vs cooldown.
• Offspring spawn diagnostics now include async failure logging, and newborns spawn slightly higher with child hearts for easier visual confirmation.
• Non-baby-variant life-stage scaling now uses smaller juvenile defaults again (baby=0.55, adolescent=0.80) now that juvenile model-visibility issues were fixed.
• Breeding offspring placement now prioritizes wider horizontal offsets and higher vertical fallback offsets to reduce parent-overlap/terrain clipping.
• Breeding heart-particle spawn now resolves NPC role-template ParticleOffset when available (with fallback to default offset), so vanilla and third-party templates can control breeding particle placement.
• Juvenile model scaling now preserves random attachment IDs from the current model when rebuilding scaled models, fixing invisible offspring where required attachments were being dropped during scale updates.
• Template_Tamework_Example/Template_Tamework_Example_Vanilla now use wander-driven Idle behavior and an explicit Follow state, and the example command item now sets Follow/Recall to state Follow.
• Breeding offspring progression now creates a vanilla family flock (new flock per breeding family), assigns one parent as the flock anchor, and moves the other parent plus offspring into FlockFollow behavior using a new Component_Tamework_Instruction_Flock_Follow_Wander asset (vanilla leash-to-leader + local wander).
• Linked companions panel cards now render up to three rolled trait indicators with icon glyphs and directional ring-fill progress (counter-clockwise green for above-default values, clockwise red for below-default values).
• Trait indicator icons in the linked companions panel now show hover tooltips with full trait names and normalized value context (current / max plus percent of max).
• Trait-based max-health scaling is now wired through MaxHealthMultiplier, applying/removing a dedicated health-max stat modifier during progression bootstrap, offspring initialization, and command respawn restoration.
• Existing companions with persisted traits now have trait stat modifiers resynced on world/entity load via CompanionTraitStatSyncSystem, so health trait effects no longer require retriggering tame/bootstrap flows.
• Linked companions panel cards now keep health as a bar and render happiness/hunger/thirst as compact circular progress meters with hover tooltips, reducing card crowding while preserving quick-status visibility.
• Linked companions panel needs rings now render texture icons (happiness/food/water) instead of letter glyphs, preserving 32x32 source art while displaying icons at compact ring-center size.
• Linked companions panel cards now render health value text directly over the health bar (current/max) using a centered overlay for better space usage and readability.
• Linked companions panel card container spacing has been tightened (reduced card height/top offset) to remove excess blank space between card content and the next entry.
• Linked companions panel now keeps framed card-row backgrounds while removing the list viewport frame to avoid a nested/double-layered panel look.
• Linked companions panel list top inset has been reduced so the first card sits closer to the subtitle/separator area, matching side inset spacing more closely.
• Linked companions trait rings now support optional texture icons from trait config (TwTraitConfig.Traits[].IconPath); trait icon glyph fallback remains in place when no icon path is configured.
• Trait roll count per spawn now supports weighted variable outcomes (Selection.RollCountWeights for 0..4), with default weighting centered on 2 rolls and 4-roll outcomes kept rare.
• Trait selection config has been simplified to remove stacked fallback layers: Selection.MaxTraitsPerNpc is now the single count/cap control, duplicate handling is unified under Selection.AllowDuplicateTraits, and legacy Selection.RerollDuplicates + Stacking fields are removed.
• Trait inheritance now supports per-trait inheritance weighting (Traits[].InheritanceWeight) and same-direction parent alignment range bias (Inheritance.PairAlignmentRangeInfluence) so high-high or low-low pairings can push offspring values further toward configured trait bounds.
• Trait schema now separates natural-spawn vs breeding ranges (Traits[].NaturalMin/NaturalMax and Traits[].BreedingMin/BreedingMax): spawn/non-inherited rolls use natural bounds, while inherited/mutated rolls and trait UI "max possible" calculations use breeding bounds.
• Added baseline trait definitions for swiftness, toughness, strength, and foraging luck in the default trait config.
• Swiftness now applies runtime move-speed effects by snapping MoveSpeedMultiplier trait values to quantized Entity/Effects tiers (Tw_Trait_MoveSpeed_###).
• Renamed the harvest double-drop trait display name from Foraging Luck to Bounty for clearer harvest-output semantics.
• Added baseline Size trait definition in default trait config (SizeMultiplier) so life-stage/adult scale can roll from trait progression.
• Damage processing now applies trait multipliers for both incoming (DamageTakenMultiplier) and outgoing (DamageDealtMultiplier) damage.
• Harvest interactions can now trait-proc double drops via HarvestDoubleDropChanceMultiplier (interpreted as chance = clamp(multiplier - 1, 0..1)).
• Template-driven harvest drops now use TameworkHarvestDrop, enabling Bounty trait bonus drops in $Harvest state flows (not only interaction Effects.DropItem).

Fixed

• Tamework's embedded jar asset pack now registers into AssetEditor's data-source map when missing, so Tamework assets appear in the pack dropdown as read-only and can be duplicated into custom packs.
• Fixed a world-thread crash in CommandLinkedNpcDeathService when recording death snapshots for linked NPCs that had neither shared happiness nor breeding happiness (null-safe fallback now avoids Double auto-unboxing).
• Tamed companions and companions with persisted custom names are now opted out of vanilla overpopulation despawn checks, preventing accidental despawn of owned/named NPCs.
• Needs-seek runtime now immediately exits to parent completion state when no readable seek target is present, preventing companions from getting stuck in NeedsSeekFood.Default / NeedsSeekWater.Default.
• Needs-seek movement now uses pathfinder by default and aborts immediately when nav reports Defer, preventing companions from remaining stuck against blocked/unreachable resource targets (for example encased food containers).
• Needs-seek now applies a failed-seek cooldown timer (NeedsSeek_Failed_Cooldown) and sensor-side cooldown gating, preventing rapid re-entry loops into needs-seek states when nearby targets repeatedly fail pathing.
• Fixed breeding pair state completion flow so BreedPair no longer stalls after arrival, and breeding pair start now clears lingering status posture animation to prevent slide-like movement.
• Breeding pair completion now uses timer-driven exit flow (arrival delay + move-timeout fail-safe), and close-range completion follows SeekStopDistance + 0.15 for tight pair-up spacing without getting stuck in BreedPair.
• Tamed companions now self-heal missing/invalid shared happiness state on world load (including NaN/non-finite values), so reloads no longer leave companions reporting "no tracked happiness state."
• Companion progression bootstrap-on-load now waits for both NPC + TameworkTamedComponent before running, fixing a load-order race where some tamed companions could skip happiness/progression bootstrap after reload.
• Companion progression bootstrap-on-load now defers work through CommandBuffer.run(...), preventing chunk-load crashes from direct Store.putComponent(...) calls during store-processing callbacks.
• Breeding offspring progression now bootstraps tamed newborn progression immediately after spawn, ensuring shared happiness state exists at birth instead of appearing as unavailable until a reload heal pass.
• Passive needs ticks no longer apply manual feed gains each sweep; manual needs refill remains interaction-driven only.