PassivePhantoms

1.3.0-Dev1a (2026-03-19)

• Added Folia support baseline for passivephantoms.
• This release was branched from the latest version to avoid breaking existing installs.
• Internal migration/update compatibility checks were reviewed for this version line.

[1.2.6] - 2025-03-09

Added

• Locktight-style config migration (config_version, merge with default, preserve comments).
• Modrinth update checker (async; notifies ops on join via passivephantoms.notify). Supports dev versions (e.g. -Dev1a, 1.2.6b1).
• Config options: update_checker, spawn_check_radius, end_spawn_interval_ticks. All numeric settings validated and clamped to safe ranges.
• Per-spawn cap now uses phantoms near the player (within spawn_check_radius) so flying phantoms can’t bypass the limit; End spawn event also enforces per-chunk cap.

Changed

• Spawn cap is radius-based (default 64 blocks) instead of chunk-only. Stuck/tree logic runs only for phantoms within 128 blocks of a player. Entity counts use getNearbyEntities for performance.
• Config comments and status command updated. Early exit when end_spawn_chance is 0.

Fixed

• Memory: cleanup on phantom death (all tracking maps), clear all maps on disable, prune stale UUIDs from aggressive set in movement monitor.
• max_phantoms_per_chunk now enforced correctly when AFK in the End (was bypassed by phantoms leaving chunk).

Note: Movement improvements are experimental and phantoms may still get hung up on chorus trees.

Added

• Movement improvements: Automatic stuck detection and escape assistance for phantoms
• Natural tree avoidance: Guides phantoms to fly around chorus fruit trees using gentle velocity adjustments
• Enhanced status command: Shows plugin status and movement improvement status

Configuration

• phantom_settings.movement_improvements_enabled: Enable/disable movement improvements (default: true)
• phantom_settings.stuck_detection_ticks: How often to check for stuck phantoms (default: 100 ticks = 5 seconds)
• phantom_settings.stuck_threshold: Consecutive checks before considering stuck (default: 3)
• phantom_settings.stuck_distance_threshold: Minimum movement distance (default: 1.0 blocks)
• phantom_settings.max_stuck_attempts: Maximum escape attempts before removal (default: 5)
• phantom_settings.tree_avoidance_enabled: Enable/disable tree avoidance (default: true)
• phantom_settings.tree_avoidance_radius: Detection radius for chorus fruit trees (default: 3.0 blocks)

Technical Details

• Single optimized monitoring task handles both stuck detection and tree avoidance
• Tree avoidance uses gentle velocity adjustments instead of teleportation for natural flight
• Stuck detection uses distance-based movement tracking with configurable thresholds

Added

• Per-chunk mobcap system: Prevents infinite phantom spawning with a limit of 8 phantoms per chunk
• Configurable mobcap: New phantom_settings.max_phantoms_per_chunk setting allows server admins to adjust the per-chunk limit
• Mobcap monitoring: Enhanced /passivephantoms status command shows phantom populations per world
• Chunk-based spawning: Phantoms now spawn based on chunk limits rather than world-wide limits
• Better distribution: Prevents single players from hogging all phantoms in a world
• Debug logging: Shows chunk coordinates and mobcap status in debug messages. Enable debug_logging: true to see when chunk mobcaps are reached.

Changed

• Spawn system: Changed from per-world (15 phantoms) to per-chunk (8 phantoms) limits
• Performance: More efficient phantom counting using chunk-based calculations
• Fairness: Better phantom distribution across multiple players in different areas
• Configuration: Mobcap is now configurable instead of hardcoded
• Logic robustness: Mobcap logic is robust and tested; no chunk will ever exceed the configured limit, mirroring vanilla mobcap enforcement.

Technical Details

• Uses chunk coordinates (blockX >> 4, blockZ >> 4) for efficient counting
• Each chunk can independently have up to the configured limit (default: 8 phantoms)
• Multiple chunks can each reach their limit, allowing higher total phantom populations
• Maintains compatibility with multiple End worlds
• Configurable mobcap supports values from 5 (conservative) to 15+ (generous)
• Mobcap enforcement is logged when debug_logging is enabled

Fixed

• CRITICAL: Fixed phantom targeting issue where Phantom aggresion would randomly break
• CRITICAL: Fixed phantom aggression persistence - phantoms now stay aggressive after being hit
• Changed event priority from LOWEST to HIGH for better compatibility with other plugins
• Improved phantom damage event handling to ensure immediate aggression
• Fixed targeting logic to properly handle null targets for aggressive phantoms
• Added immediate re-targeting for aggressive phantoms when they lose their target
• Fixed variable scoping issues in lambda expressions

Added

• New /passivephantoms debug command to toggle debug logging in-game
• New /passivephantoms status command to check plugin status and aggressive phantom count
• New /passivephantoms list command to list all aggressive phantoms and their current targets
• Enhanced debug logging with phantom UUIDs for better troubleshooting
• Tab completion for all /passivephantoms commands with smart filtering
• Comprehensive tracking of when phantoms are added/removed from aggressive set

Changed

• Updated version to 1.2.5 to reflect critical bug fixes
• Improved command help messages with new subcommands
• Enhanced targeting event logging to show target information and aggressive status
• Better error handling and safety checks for phantom targeting

Technical Details

• Aggressive phantoms now re-target immediately when they lose their target (null)
• Re-targeting uses next-tick scheduling to avoid event conflicts
• Only re-targets when phantom actually loses target, not constantly
• Preserves natural phantom AI attack cycles while maintaining aggression