LovelyLib

1.0.0 — 2026-07-04

Minecraft 1.21.1

⚠️ Breaking changes. Several classes were renamed as part of the ADR_018 ecosystem terminology rename. Any mod built against 0.1.0-alpha must update its imports. See below.

First stable release. Introduces the full NBT data pipeline, complete AI goal set, save migration chain, the Tribute variant with isolated animation profile, config-driven stat system, and the animation missing-wire fix that activates the profile-aware animation path for all robots.

Breaking: Class Renames (ADR_018)

These renames align with the Family / Variant / Appearance three-tier vocabulary established in HZLib 1.0.0. Robot* = LovelyLib tier. *Families = registry/collection class. *Family = single family descriptor.

NBT Data Pipeline

Robot entity data is now fully managed through the HZLib EntityDataSchema / DataField<T> pipeline. All robot NBT fields are declared in RobotFields — the single source of truth. No string literals appear at call sites.

RobotFields — typed field handles:

IDLE_STATIONARY_TICKS is persisted so the idle animation state (rest vs sit) is restored correctly on world reload without resetting the delay threshold. STANDBY_TICKS and STANDBY_TARGET_TICKS are retained as load-only fields for save compatibility — they are read on migration but never written.

Schema version: 1.0.0

Migration chain (three steps, registered in RobotFamily.configureSchema()):

• MigrationStep_V0_Fabric — Gen1-Fabric locale strings (entity.rlovelyr.bunny) → stable variant keys. Hardcoded lookup table. Must be maintained as append-only.
• MigrationStep_V0_Forge — Gen1-Forge / Gen2 flat PascalCase format → EntityData compound. Writes SchemaVersion and McVersion.
• MigrationStep_V1_1204 — 1.20.4 flat int-ID format (including TextureID integer → string variant key) → EntityData compound.

Each step is idempotent — already-migrated saves skip silently.

Animation: Missing-Wire Fix (ADR_022 Change C)

The AnimationProfile is now passed directly into the StandardAnimatorVariant constructor in RobotFamily.configureVariants(). This closes the root missing wire identified in ADR_022: previously, AnimationStateManager.resolveProfile() returned null for every robot entity because the profile was only attached as a family feature — which Step 1 of the resolver never checks. With the wire closed, the entire profile-aware animation path is active for all robots.

ROBOT_BASE_PROFILE (Legacy and Reboot):

• Named slots: idle, walk, rest, sit, attack (INTERRUPT)
• Idle slot 1 — rest: activates when in Standby, priority 1, threshold 0 ticks
• Idle slot 2 — sit: activates when in Standby OR isInSittingPose(), priority 2, threshold StandbyToSitDelayMin (600 ticks / 30 seconds). The isInSittingPose() OR condition breaks the first-frame SynchedEntityData race on world reload — if the robot was floor-sitting when saved, the sit animation plays on the very first render frame.

TRIBUTE_PROFILE (Tribute only):

• Named slots: idle, walk, sit (mapped to "rest"), attack (INTERRUPT)
• No idle slots — Tribute robots hold the upright rest pose indefinitely in Standby, faithfully reproducing the original mod behaviour
• .sit("rest") is intentional: the vehicle branch in AnimationStateManager checks the sit pool first when riding; pointing it at "rest" ensures Tribute robots play the stand-at-ease animation in vehicles rather than the floor-sit pose

buildAnimatorProfile() override point: Subclasses override this method (not a constructor parameter) to return their profile. TributeRobotFamily overrides it to return TRIBUTE_PROFILE. The base class returns ROBOT_BASE_PROFILE.

Color Palette System

RobotFamily.withColorPalette() registers the full 16-color dye palette and a ConditionalAppearanceFeature that maps each dye item to a texture variant key. Three overloads:

• withColorPalette(RobotVariant) — full 16-color palette, textures in lovelylib: namespace
• withColorPalette(RobotVariant, List<EntityTexture>) — restricted palette (e.g. Bunny3 with 5 pastel colors)
• withColorPalette(RobotVariant, List<EntityTexture>, String namespace) — restricted palette in a custom namespace (used by Tribute to resolve textures from lovely_robot:)

Registry key strategy: when namespace differs from lovelylib, variant keys are prefixed with the namespace (e.g. "t_bunny_pink") to prevent collisions with lovelylib's own registrations for the same variant/color.

EntityTexture enum — 16 named dye colors (WHITE through BLACK) plus RANDOM. Used for palette declarations in TributeRobotFamilies and LegacyRobotDefinitions.

Family Registries

LegacyRobotFamilies:

• Populates from RobotDefinitionRegistry rather than hard-coded static fields. Adding a new Legacy robot requires only a builder call in LegacyRobotDefinitions — no change to LegacyRobotFamilies itself.
• initialize() must be called after Lovely.onInitialize() seals the registry and before any deferred register supplier fires.
• reloadFromConfig() applies per-variant stats (HP, attack, defense, speed, max level) and standard features (LevelFeature, CombatLevelFeature, EnchantmentFeature, ProtectionFeature) from current config values at runtime.

TributeRobotFamilies:

• 4 robot types: VANILLA, BUNNY, BUNNY2, HONEY — the original four from the 1.12.2 mod.
• Restricted color palettes faithful to the original: Bunny (5 colors), Bunny2 (2 colors), Honey (3 colors), Vanilla (4 colors).
• Textures resolved from lovely_robot: namespace via the createTribute() factory.
• All four use TRIBUTE_PROFILE via TributeRobotFamily subclass override.

AI Goal Set

AiBaseDefenseGoal (Legacy / Reboot):

• PATROL ↔ GUARD state machine. PATROL: 30–45 seconds of wandering within base radius. GUARD: 20–30 seconds stationary at base with active scan pattern.
• Four scan patterns selected randomly per guard cycle (weighted): FULL_SCAN (25%) — single 360° rotation; DOUBLE_SWEEP (30%) — two 180° sweeps; QUADRANT_CHECK (25%) — four 90° cardinal checks; RANDOM_POINTS (20%) — 4-6 random perimeter points.
• Combat pauses the state machine; resumes seamlessly after the threat is eliminated.
• Emergency teleportation if robot exceeds warp range from base; attempts to walk back if within 2× warp range.

AiTributeReturnToBaseGoal (Tribute):

• Faithful translation of the original EntityAIBunnyFollowPoint from the 1.12.2 archive.
• No PATROL/GUARD cycle — Tribute robots return directly to base in Defense state and hold position.
• canContinueToUse() checks navigation.isDone() first — dead paths exit cleanly instead of locking the robot in place.
• moveTo() is unconditional (not gated behind a boolean return) — gating caused a dead zone where a failed path inside warp range left the robot stationary with no recovery.

AiFollowOwnerGoal — follows owner in Follow state, respects min/max distance config.

AiConditionalWanderGoal — owner-stationary-aware wander with configurable chance, radius, duration, and cooldown.

AiConditionalLookGoal / AiConditionalRandomLookGoal — look goals with configurable range.

AiAutoAttackGoal — configurable auto-attack with attack chance and target type filtering.

RobotLookControl — custom look control for smooth robot head tracking.

API Features

• CombatLevelFeature — scales HP, attack, and defense with level using a pluggable IAttributeCalculationStrategy. Used by both Legacy and Tribute via LinearAttributeStrategy.
• ProtectionFeature — level-based damage type resistance (fire, fall, blast, projectile) with per-type caps and enchantment integration. Cap values configurable via SharedConfigs.
• EnchantmentFeature — looting and sharpness enchantment integration. Configurable max level and looting chance.
• BlazeCycleFeature — fire-cycling behavior for Dragon variant.
• BlockAllItemInteractionFeature — blocks all item interactions (used for Tribute robots that should not accept dye recoloring).
• BoneVisibilityConditions — factory methods for common BoneCondition predicates: tailVisible(int tailIndex), textureVariantIs(String key), textureVariantIsNot(String key). Used with HZLib's BoneVisibilityFeature for Kitsune tail progression.

Config System

SharedConfigs.Common — server-authoritative values, synchronized to clients:

• Movement speeds (melee, follow, wander)
• Follow distances (min, max)
• Experience formula (base + level × multiplier)
• Combat (friendly fire, attack chance, heal interval, wary time, auto-heal)
• Looting enchantment (enabled, max level, looting chance)
• Base defense (range, warp range)
• Protection caps (fire, fall, blast, projectile — default 80%)
• Enchanted book protection (enabled, contribution percentage)
• Smart Core Retrieval (enabled, distance)
• AI behavior (owner-still threshold, wander params, patrol/guard durations, scan rotation speed)
• Collision avoidance (enabled, detection radius, min spacing)
• Animation (standby-to-sit delay: 600–1800 ticks)

SharedConfigs.Client — client-only:

• ShadowRadius — renderer shadow size

SharedConfigs.EntityConfigData — per-variant stat container with validation, validateOrDefault() fallback, and builder pattern.

Items

• LovelyCoreItem — robot core item base class. Carries robot data (variant, color, stats) as item NBT.
• BaseSpawnItem — spawn item base for deploying a robot from inventory.

Commands

• LovelyCommands / NativeCommands — /llovely command tree: list, summon, teleport, stats, config.
• ColorArgumentType / ColorArgumentTypeInfo — custom command argument type for 16-color dye names, with tab-completion.

Utilities

• EntityDataHelper — helpers for reading/writing entity data compounds.
• EntitySpawnHelper — helpers for spawning robot entities with correct initial state.
• NbtProcessingUtils — NBT processing utilities used during migration and save/load.
• ValidationUtils — general validation helpers.
• BoneVisibilityConditions — see API Features above.