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