MeteorEvents | Cinematic Meteor Loot

1. Introduction & Overview

MeteorEvents introduces cinematic celestial events to Minecraft servers. Rather than instant unannounced block explosions, meteors traverse the sky along configurable atmospheric entry trajectories rendered via PacketEvents. Falling meteors feature spinning volumetric display entities (giant fire charges, snowballs, ender eyes) tumbling along multi-axis rotational curves with high-altitude supersonic trails visible up to 256+ blocks away.

Upon impact, the plugin creates virtual packet craters and towering plumes of smoke without griefing or corrupting server world saves. An interactive cooldown hologram protects the core during a cooling period before players can open the loot inventory. Once claimed, the destabilizing crater remnants vanish cleanly after 30 seconds.

2. Features & Detailed Functionality

• 5-Stage Event Lifecycle: Warning omen sky tremors, atmospheric crossing, explosive shockwave impact, interactive cooldown exploration, and post-loot vanishing cleanup.
• Spinning Packet Display Entities: Meteors are rendered as client-side packet entities with dynamic scale (up to 5.5x) and tumble rotations (yaw +28°, pitch +18° per tick).
• 100% Virtual Packet Craters: Impact craters and destroyed terrain are delivered through client-side packet changes. Real server blocks are never permanently modified.
• Towering Smoke Plumes: Configurable columns of campfire signal smoke billow from the crater perimeter throughout the exploration phase.
• Directional 3D Audio with Auto-Cutoff: Flight audio originates from the exact 3D coordinates of the falling meteor. Flight audio immediately halts upon impact, preventing infinite audio loops.
• Interactive Countdown Holograms: Floating ArmorStand packet holograms count down the cooling period and vanishing phases in real time.
• Loot Chest & Fragment System: Interactive core chest with custom display names, weighted item rolls, enchantments, and mineable meteorite fragments.
• Folia Multi-Threaded Region Scheduling: Native support for Folia regionized threading as well as Spigot and Paper.

3. Requirements & Dependencies

4. Supported Platforms & Versions

• Supported Minecraft Versions: 1.16.5, 1.17.x, 1.18.x, 1.19.x, 1.20.x, 1.21.x, and 26.x
• Supported Server Platforms: Paper, Spigot, Purpur, and Folia

5. Installation

1. Download and install PacketEvents 2.14.0+ into your server's plugins/ folder.
2. Place MeteorEvents.jar into your plugins/ folder.
3. Restart your server to generate the configuration files.
4. Configure your desired settings in config.yml, meteors.yml, messages.yml, rewards.yml, and protections.yml.
5. Run /meteorevents reload to apply updates without restarting.

6. Commands & Usage Examples

7. Permissions

8. Configuration Options & Examples

MeteorEvents features 5 organized YAML configuration files with full documentation comments:

# Master toggle to enable automated meteor events.
enabled: true

scheduling:
  check-interval-seconds: 60
  chance-percentage: 25.0
  min-cooldown-seconds: 600
  max-concurrent-events: 2
  min-players-online: 1
  allowed-worlds:
    - world

performance:
  view-distance: 256
  update-rate-ticks: 1
  max-particles-per-tick: 80

stages:
  omen-duration-seconds: 10
  core-lock-seconds: 30
  post-loot-vanish-seconds: 30
  default-exploration-seconds: 600

meteors:
  ember:
    display-name: "&6&lEmber Meteor"
    rarity: "COMMON"
    weight: 50
    speed: 0.85
    start-height: 160
    horizontal-offset: 120
    visual-entity: "FIRE_CHARGE"
    visual-entity-scale: 3.8
    smoke-plumes-enabled: true
    smoke-plumes-count: 10
    trail-particles:
      - "FLAME"
      - "LAVA"
      - "CAMPFIRE_COSY_SMOKE"
    crossing-sound: "ENTITY_FIREWORK_ROCKET_BLAST"
    impact-sound: "ENTITY_GENERIC_EXPLODE"
    crater-radius: 4
    crater-depth: 3
    exploration-duration-seconds: 600
    lock-duration-seconds: 30

9. Integrations & Optional Dependencies

• WorldGuard 7+: Automatically detects protected regions, plots, and claims. Meteors will never land inside regions where block-break or explosions are restricted.
• PlaceholderAPI: Supported across message templates and broadcasts using {meteor}, {world}, {x}, {y}, {z}, {player}, and {time}.

10. Performance Considerations

• Zero Terrain Churn: Virtual packet craters avoid writing thousands of block state updates to chunk storage or disk, avoiding save stalls.
• Pre-Calculated Flight Vectors: Particle trajectories, spiral spirals, and supersonic cones are pre-calculated once per tick rather than duplicated across player loops.
• Distance-Filtered Packet Distribution: All particle and entity packets are selectively dispatched strictly to viewers within configurable view distance radii.
• Folia Native Region Safety: Region-bound operations are dispatched directly through regional schedulers without blocking adjacent world threads.

11. Known Limitations

• Packet display scaling (3.8x to 5.5x) requires clients connecting on 1.19.4 or higher for full visual model magnification. On older clients, PacketEvents smoothly falls back to standard projectile packets.
• Because crater blocks are client-side virtual packets, players may experience momentary client resynchronization if they attempt to mine protected non-fragment blocks.

12. Troubleshooting & FAQ

Q: Why does the meteor sound continue after landing?
A: Make sure you are running version 1.1.0+. In this version, non-looping audio cues are utilized and stopSound packets are dispatched on impact.

Q: Why does the crater disappear after 30 seconds?
A: The crater is a virtual packet display. You can customize this timer via stages.post-loot-vanish-seconds in config.yml.

Q: Can players grief the crater before looting?
A: No. The impact area is protected against breaking, placing, bucket usage, and pistons until the core is looted.