Familiars: Reimagined API

[0.2.6 Alpha]

-- General
- Added Annotation-based familiar definition system Alternative to JSON files for declaring familiars, quests, and abilities in code
- Added Registration statistics tracking FamiliarsReimaginedAPI, AbilityActionManager, QuestActionManager, AbilityRegistry, QuestRegistry, JsonGenerator granular count methods for familiar abilities, standalone abilities, familiar quests, standalone quests, and auto-generated familiars per mod
- Added Server-authoritative architecture Server is single source of truth with client-side temporary display cache (787 lines removed from FamiliarSaveLoadHandler)
- Added 3-Layer TOML Configuration System Global config (baseline for all worlds) → World-specific config (overrides) → Player NBT (individual progress)
- Added GlobalConfigHandler Auto-generation, validation, auto-repair, reference file generation, and runtime TOML editing support with intelligent validation and fallback values
- Added InventoryButtonPosition Server-side configuration system with position cycling, network sync, and reset command (DEFAULT, TOP_LEFT, BOTTOM_LEFT, BOTTOM_RIGHT, HIDDEN)
- Added Creative Mode Familiars Menu button
- Added FamiliarsServerMenu disable and enable button textures
- Added Quick Swap Slot removal buttons to Familiars Menu interface
- Added QuickSwap Network Packets QuickSwapSlotSyncPacket for client sync, QuickSwapCyclePacket and QuickSwapSetSlotPacket for server-side slot management
- Added TomlConfigHandler Automatic backup system, corruption detection with recovery, and dirty tracking for partial saves (only modified familiars saved on logout and menu close)
- Added selection sound to familiar icons
- Added IFamiliarSummon group dismissal Shift-click dismisses all summons of the same type, with canDismiss() override for custom dismiss conditions
- Altered ClientMenuSettings Moved menu state persistence from server-side per-world to client-side per-player (scroll position, sort state, selected pack now follow player across worlds), added HUD button position persistence
- Altered CustomParticleGroup Performance improvements and renamed from ParticleGroup to avoid vanilla naming conflict
- Altered FamiliarsMenu name to Familiars
- Altered FamiliarsMenu Server-authoritative display with real-time data requests and comprehensive cache integration
- Altered FamiliarsMenuButton Now supports configurable positioning via server settings with hide option
- Altered FamiliarsServerSettingsMenu Forged familiar buttons now render entity models instead of generic icons
- Altered FamiliarsServerSettingsMenu Integrated with 3-layer TOML system with batched saves on menu close and server template changes propagating to all online players
- Fixed CooldownBarRenderer Ability icons now correctly use owning familiar instead of active familiar
- Fixed DynamicForgedFamiliarGoalInjector Attack speed and movement speed attributes now enforced every tick for forged familiars
- Fixed DynamicForgedFamiliarGoalInjector Flying mobs now respect movement speed attribute when pathfinding
- Fixed EntityRidingOffsetMixin Riding offsets now rotate with vehicle facing direction (X and Z work properly)
- Fixed EntityRidingOffsetMixin Player jitter while riding fixed by using moveTo instead of setPos
- Fixed FamiliarCheatsCommand Ability slot unlock state not syncing after grand unlock command
- Fixed FamiliarCleanupHandler [cleanupServerData] Ability effects now removed before clearing player data to prevent effect persistence across sessions
- Fixed FamiliarCleanupHandler Race condition where cleanup cleared data during active save operation
- Fixed FamiliarEventHandler Fire immunity now prevents daylight burning for undead familiars
- Fixed FamiliarEventHandler Players riding forged familiars now immune to fall damage
- Fixed FamiliarEventHandler [spawnFamiliar] Optimized player respawn for faster familiar spawning
- Fixed FamiliarSaveLoadHandler Critical race conditions causing data loss and ClassNotFoundException errors during save/load operations, added comprehensive quickswap serialization logging with slot count tracking and validation
- Fixed FamiliarUnlockManager Prevents re-locking familiars when server settings change quest assignments, checks both unlock flag and quest completion during login to prevent re-locking when unlock flag temporarily cleared
- Fixed FamiliarsMenu Familiar XP requirements not syncing on initial menu open (sends RequestFamiliarXpSyncPacket on menu construction to populate client-side unlock managers)
- Fixed FamiliarUnlockSyncPacket and UnlockAbilitySlotPacket XP not deducted server-side, causing XP to revert when player gains levels (server now properly deducts XP cost before unlocking)
- Fixed FamiliarsMenu UI issues (tooltips drawing under elements, XP button highlights when disabled)
- Fixed FamiliarsServerSettingsMenu Multiple issues (ability slot quest requirements not saving to TOML, tooltip rendering, scroll persistence, missing cache)
- Fixed ForgedFamiliarCreationScreen Render toggle button now identical to FamiliarsMenu (15x15 size, consistent styling)
- Fixed ForgedFamiliarShoulderHandler Name tags now hidden when familiar is on player shoulder
- Fixed PlayerEventHandler Abilities no longer stack on relog due to NBT restoration before cleanup
- Fixed PlayerEventHandler Active familiar removed before logout to prevent duplication
- Fixed PlayerEventHandler Duplicate spawning on login and respawn lag via optimized familiar spawning
- Fixed QuickSwapHudOverlay Icons now start bright and become bright on swap, then fade after idle period (fixed initial opacity and swap behavior)
- Fixed QuickSwapManager Singleplayer data loss on logout by removing client-side clearAllData() call that cleared server data before save, added debug stack trace logging
- Fixed RequestFamiliarListPacket Ability slot unlock states not syncing when opening familiar menu
- Fixed SaveServerCustomizationsPacket Layer 3 player-specific unlock data overwritten by server template on menu save
- Fixed SyncAllForgedFamiliarsPacket Singleplayer registry clearing causing forged familiar unlock states to reset
- Fixed XP buttons making interaction noises when disabled
- Removed FamiliarUnlockManager Verbose logging that cluttered console
- Removed FamiliarsMenuSettingsMenu and changed button to open server settings directly
- Removed FamiliarsServerSettingsMenu Per-button-click save operations (replaced with batched saves for performance)
- Removed Debug logging from FamiliarSaveLoadHandler, ForgedFamiliarInventoryHandler, ServerEventHandler, ClientEventHandler, QuickSwapManager, ForgedSoundLibrary, ForgedFamiliarCreationScreen for production cleanliness

-- Quest
- Added ClientToServerQuestProgressUpdatePacket Server-side validation to prevent quest progress spoofing (player ID verification, progress range validation, familiar unlock verification, ability slot quest active familiar check)
- Altered ClientQuestProgressHandler and QuestProgressSyncPacket Single-player storage optimization (~70% memory reduction), added validation to verify quest data is for current player
- Fixed ItemQuestHandler Improved item quest tracking and validation
- Removed ClientQuestProgressHandler Tick-based cleanup and multi-player storage (now logout-only cleanup, current player only)

-- Ability
- Added AbilityActionManager [needsTickProcessing] Early exit optimization for tick handler (80-95% overhead reduction for idle players)
- Added FamiliarDataFactory [getAbilityMetadata] Get full metadata for any ability (familiar or standalone)
- Added FamiliarSaveLoadHandler Effect state persistence for state-based effects with serialization/deserialization
- Added MobEffectFactory Aura systems with configurable radius, amplifier, and duration (blindness, levitation, poison, slowness, weakness, wither, fire, freezing)
- Added MobEffectFactory Thorns damage reflection systems (normal, fire, poison, wither, freezing)
- Added EffectCreationFactory [createCraterEffect] Batched ground chip particles via CustomParticleGroup instead of per-block particle spam
- Fixed AsyncPlayerDataManager Removed redundant FamiliarSaveLoadHandler.loadPlayerData call that ran before login sync
- Improved AbilityActionManager Replaced reflection with MethodHandles for 50-90% faster ability execution

-- Standalone
- Added AbilityActionManager Standalone ability system with activation, deactivation, state checking, and hotkey triggering
- Added FamiliarDataFactory Standalone ability factory wrappers (zSTANDALONE_* methods)
- Fixed AbilityActionManager [tickAbilities] Now ticks standalone abilities even without active familiar
- Fixed FamiliarCleanupHandler Cleanup of standalone abilities on player logout

-- Forged Familiar System
- Added FamiliarSizeCategory Enum for categorizing familiar sizes (SMALL, MEDIUM, LARGE, EXTRA_LARGE)
- Added ForgedSoundLibrary Utility for managing forged familiar sound playback
- Added UI textures Hovered states for all buttons (HUD positions, settings, sound, XP) and forged_familiar_icon.png for menu display
- Added ClientForgedPacketHandlers Client-side handler for forged familiar packets with DistExecutor isolation
- Added ForgedFamiliarClientUtil Client-only utilities for entity capture and render instance creation (prevents dist-cleaner crashes)
- Added ForgedFamiliarHitboxScalingHandler Server-safe hitbox scaling event handler (separated from visual scaling)
- Added ForgedScaleHelper Utility for forged familiar scaling calculations with getAllForgedFamiliarIds() for cleanup operations
- Added SyncAllForgedFamiliarsPacket Bulk sync packet for all forged familiars on world load and player login
- Added ForgedFamiliarMetadata Complete metadata structure (entity type, display name, rarity, scale, menu scale, y-offset, description, texture, GeckoLib flag, position sync mode, name tag visibility) with validateEntityType(), added useGeckoLibRender field for render mode preference
- Added ForgedFamiliarRegistry Global registry for player-created forged familiars with metadata management and updateForgedFamiliar() method
- Added DynamicForgedFamiliarRegistry Tracking system for AI-mode forged familiars spawned as real entities
- Added ForgedSummonClientSync Client-side entity registration queue to handle packet race conditions
- Added ForgedSummonGoalInjector AI goal injection system for forged familiar summons with owner-following behavior
- Added ForgedFamiliarCreationScreen Full-featured UI for creating, editing, and managing forged familiars with live preview
- Added ForgedFamiliarCreationRenderHelper Rendering utilities for forged familiar preview with GeckoLib and vanilla entity support
- Added MultiLineEditBox Multi-line text editing component for forged familiar descriptions
- Added SimpleFamiliarEntity Wrapper entity for sync-mode forged familiars with teleportation and display
- Added DynamicFamiliarRenderer Custom renderer for SimpleFamiliarEntity with GeckoLib and vanilla entity support
- Added ForgedFamiliarScalingHandler Event handler for applying forged familiar scale to entity dimensions via Mixin
- Added Forged Familiar Network Packets Server packets (CreateForgedFamiliar, UpdateForgedFamiliar, DeleteForgedFamiliar, OpenForgedInventoryPacket) and client sync packets (SyncForgedFamiliar, SyncForgedFamiliarDelete, SyncForgedSummon, SyncForgedMetadataUpdate)
- Added FamiliarSummonHandler Event handler for forged summon combat rules (prevent targeting owner/allies)
- Added IFamiliarSummon Interface for forged familiar summons
- Added TomlConfigHandler Forged familiar TOML operations (saveForgedFamiliarsToToml, loadForgedFamiliarsFromToml, getForgedFamiliarsDirectory), added has_inventory and inventory_size field persistence
- Added FamiliarRegistryAPI.registerForgedFamiliar() Registration method for forged familiars in global registry
- Added FamiliarSaveLoadHandler Forged familiar data serialization and deserialization
- Added Forged Familiar Deletion Cleanup methods (AbilityActionManager.clearAbilitiesForFamiliar, AbilitySlotUnlockManager.clearSlotsForFamiliar, FamiliarUnlockManager.removeForgedUnlocks)
- Added ClientRendererRegistry Event handler for registering forged familiar renderers
- Added ModEventBusEvents Entity registration for SimpleFamiliarEntity
- Added Namespace Tracking Register and retrieve mod namespace for ability and quest classes (AbilityActionManager and QuestActionManager methods)
- Added Shoulder Mounting System ForgedFamiliarShoulderHandler and rendering layer for mounting small forged familiars on player shoulders
- Fixed ForgedFamiliarShoulderHandler Enigmatic Legacy item ejection when forged familiars modify shoulder data (replaced player.load() with direct setter methods to avoid Curios capability re-validation)
- Added Rideable System ForgedFamiliarRideableHandler with jump input packet, step height sync, and movement controls
- Added Inventory System ForgedFamiliarInventoryHandler for persistent per-familiar-type storage with automatic size adjustment, ForgedFamiliarInventoryMenu and ForgedFamiliarInventoryScreen (moved to screen/forgedfamiliarinventorymenu package), InventoryLayoutCalculator for dynamic slot positioning, hotkey-only access via ModKeyMappings and ClientKeyInputHandler
- Added Aggression Levels Four modes (passive, self-defense, guard, aggressive) with UI controls for combat behavior
- Added Equipment System Armor slots (helmet, chestplate, leggings, boots) and weapon slot (main hand) for forged familiars
- Added Stat Upgrade System Health, armor, damage, attack speed, speed, and knockback upgrades with UI controls
- Added Combat Abilities Fall damage immunity, fire immunity, invulnerability, no gravity, and attack goal toggles
- Added Movement Types GROUND, FLYING, SWIMMING classifications for AI behavior and goal injection
- Added Ender Dragon AI ForgedDragonPhaseManager and ForgedDragonFollowOwnerPhase for improved owner following
- Added Custom Renderers ForgedCreeperRenderer, ForgedEnderDragonRenderer, ForgedShulkerRenderer, MenuEnderDragonRenderer for entity-specific rendering
- Added UI Textures Complete texture set for equipment buttons, stat buttons, aggression buttons, and combat ability buttons (normal and hovered states)
- Altered Terminology Complete Runtime→Forged rename (classes, packages, packets, UI screens, handlers)
- Altered SimpleFamiliarEntity Renamed from DynamicFamiliarEntity to better reflect its purpose as a simple wrapper entity
- Altered SimpleFamiliarRenderer Renamed from DynamicFamiliarRenderer to match entity rename
- Altered Handler packages Reorganized into logical structure (familiars/handler/client/, familiars/handler/effect/, familiars/forged/handler/)
- Altered ForgedFamiliarCreationScreen Major UI improvements with enhanced layout, better component organization, enhanced preview rendering with inventory mode support
- Altered ForgedFamiliarInteractionHandler Disabled right-click inventory opening, now hotkey-only access
- Altered ForgedFamiliarRideableHandler Block dismount on interaction, require Shift+Space to dismount, optimized by moving AI/navigation/look control setup to mount-time only instead of every tick and removing redundant positionRider calls, only update rotation when changed
- Altered ClientEventHandler.onClientLogout() Now clears all familiar state (registry, unlocks, ability slots, quests) and detects singleplayer vs multiplayer to prevent TOML corruption
- Altered FamiliarBatchRegistry.processClass() Now passes modId to AbilityRegistry and QuestRegistry
- Altered Forged Familiar Syncing Server template initialization, client sync on world load/login, DistExecutor packet handling (FamiliarRegistryAPI, FamiliarSaveLoadHandler, PlayerEventHandler, ModNetworking, SyncForgedMetadataUpdatePacket, SyncForgedSummonPacket)
- Altered FamiliarUnlockManager.isFamiliarUnlocked() Server template fallback now only on dedicated server to prevent singleplayer state leakage
- Altered ForgedFamiliarCreationScreen Updated to use ForgedFamiliarClientUtil.captureFromEntityType()
- Altered ForgedFamiliarMetadata Removed client-only methods (createRenderInstance, captureFromEntityType) to prevent dedicated server crashes
- Altered ForgedFamiliarRegistry.clearAll() Now unregisters forged familiars from FamiliarRegistryAPI to prevent world state leakage
- Altered ForgedFamiliarScalingHandler Renamed to ForgedFamiliarRenderScalingHandler, moved hitbox scaling to ForgedFamiliarHitboxScalingHandler, annotated @Dist.CLIENT, removed all debug logging
- Altered ForgedScaleHelper Removed all debug and throttled logging for production
- Altered ForgedSummonClientSync Moved to familiars.forged.client package
- Altered PlayerEventHandler Added forged familiar inventory loading on player login
- Fixed AI-mode Forged Familiars Duplication, persistence, identification, and registry issues across cleanup/spawn/removal handlers (FamiliarCleanupHandler, FamiliarEventHandler methods)
- Fixed CreateForgedFamiliarPacket Now initializes empty ability slots for new forged familiars to prevent ability activation failures
- Fixed FamiliarUnlockManager.isThisPlayerUnlocked() Forged familiars no longer inherit unlock state from server template
- Fixed MultiLineEditBox Moved to screen.components package for proper organization
- Fixed Dedicated Server Crashes Client-only code removed from ForgedFamiliarMetadata and sync packets (dist-cleaner failures)
- Removed Obsolete textures minecraft_pack.png and special_pack.png from API resources
- Removed ForgedFamiliarMetadata Client-only methods (createRenderInstance, captureFromEntityType) moved to ForgedFamiliarClientUtil
- Removed Test Code TestCowFamiliar entity and TestDynamicFamiliars definitions
- Removed Debug logging from ForgedFamiliarRegistry and ForgedFamiliarRideableHandler for cleaner production output