> For the complete documentation index, see [llms.txt](https://wiki.vortexdevelopment.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.vortexdevelopment.net/projects/fallingstars/configuration.md).
# ⚙️ Configuration
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
1. **CENTER:** Spawns stars within a radius around a fixed `world,x,y,z` location.
2. **PLAYER:** Spawns stars around active players (can be throttled by chance or random pick).
3. **TIMER:** Spawns stars over a fixed period of time.
4. **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`.
{% hint style="warning" %}
⚠️ 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.
{% endhint %}
### 🛡️ 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.
{% hint style="info" %}
**Performance Tip:** If you have many players, consider disabling `Detection.Move` and relying on the `Internal Cooldown` for random spawns to reduce CPU overhead.
{% endhint %}
### 🎮 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. 
***
### 📅 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.
***
### 🎲 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.
{% hint style="info" %}
**Auto-Save:** All changes made through the GUI are automatically saved to your YAML files and applied immediately. No reload required!
{% endhint %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://wiki.vortexdevelopment.net/projects/fallingstars/configuration.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.