FallingStars is designed to be highly customizable. This page explains the key configuration options available in config.yml and how to properly set up the event system.
📝 Core Settings
The main config.yml handles global behavior and random spawning.
Falling Star Mechanics
Fall Height: The vertical distance (20.0 blocks by default) from which a star begins its descent above the target block.
Fall Duration: How long the descent animation lasts (2.5s).
Custom Name: Toggle whether stars display their configured name while falling.
Random Spawning
Random spawning allows stars to appear naturally around players without a scheduled event.
Chance: The probability (0.1% default) of a check triggering a spawn.
Internal Cooldown: How often the plugin checks each player for a potential spawn.
Player Cooldown: Prevents too many stars from spawning for the same player in a short period (e.g., 1h).
📅 Event System Configuration
Events provide structured "star showers" or rewards. They are defined in the events/ folder.
🚩 Event Types
CENTER: Spawns stars within a radius around a fixed world,x,y,z location.
PLAYER: Spawns stars around active players (can be throttled by chance or random pick).
TIMER: Spawns stars over a fixed period of time.
REGION: Automatically detects WorldGuard regions to drop stars within boundaries.
⏳ Spawn Modes & Windows
INTERVAL (Burst): Stars spawn in batches at specific or random intervals.
EVENLY (Drip): Stars are spread out smoothly across the configured Spawn Window.
⚠️ Crucial Configuration Note When using the EVENLY spawn mode or a specific Spawn Window, you MUST set a Total Max Spawns (or Max Spawns per star type). If this value is left at -1 or not properly defined, the plugin cannot calculate the "drip" rate correctly, which may result in rarely or never spawning any gifts during the window. Always ensure your max spawn limits match your expectations for the event's intensity.
🛡️ WorldGuard Integration
If WorldGuard is installed, you can restrict where stars are allowed to land.
Excluded Regions: Define a blacklist of regions (like spawn or afk) where star spawning is blocked.
Per-World Configuration: Each world can have its own mode (WHITELIST / BLACKLIST) for star spawning zones.
Performance Tip: If you have many players, consider disabling Detection.Move and relying on the Internal Cooldown for random spawns to reduce CPU overhead.
🎮 In-Game Editor
FallingStars features a powerful, real-time in-game editor that allows administrators to modify stars, events, and random spawn settings without touching a single configuration file.
🌟 Star Management (/fs stars)
The Star Management GUI is your central hub for creating and modifying star types. From here, you can customize the visual and mechanical properties of every star.
✨ Visual Customization
You can change the block type, player head skin, and even the particle effect trail that follows the star as it falls.
Material: Change the physical block of the star (supports any block or PLAYER_HEAD).
Skin URL: Apply custom textures for PLAYER_HEAD stars.
Particle Trail: Select from various preset animations (e.g., FLAME, SOUL_FIRE, GLOW).
⚙️ Behavior & Rewards
Impact Effect: Choose what happens when the star hits the ground (e.g., EXPLOSION, LIGHTNING).
Sound Radius: Control how far away players can hear the impact.
Reward Cycles: Toggle how rewards are chosen when a player collects the star. Place a GIF here showing /fs stars and clicking through star properties.
📅 Event Management (/fs events)
The Event Manager allows you to orchestrate scheduled star showers and regional drops.
🛠️ Creating Events
Step 1: Click the Create New Event button and type an identifier.
Step 2: Configure the Type (Center, Player, Region, Timer).
Step 3: Add star types to the event's "Pool" and set their individual weights.
📍 Location Settings
For CENTER events, you can set the exact coordinates by clicking a button in the GUI while standing at the desired location. For REGION events, simply type the WorldGuard region ID. Place a GIF here showing the creation of a 'CENTER' event and setting the location.
🎲 Random Spawning (/fs randomspawn)
Configure the global natural spawning behavior for your server. This GUI mirrors the config.yml settings but provides instant feedback and validation.
Global Toggles: Enable or disable random spawning entirely.
Pool Management: Add or remove stars from the natural spawning pool and adjust their spawn chances.
Throttling: Set global cooldowns to ensure stars remain rare and exciting. Place a GIF here showing how to add a star to the random spawn pool.
Auto-Save: All changes made through the GUI are automatically saved to your YAML files and applied immediately. No reload required!
Place a GIF here showing 
Place a GIF here showing the creation of a 'CENTER' event and setting the location.
Place a GIF here showing how to add a star to the random spawn pool.