# Stars.yml

Under each star type name, you can configure the following options:

***

1. item
   * **Type:** `String`
   * **Description:** The Bukkit Material name for the item that falls from the sky. Names are case-insensitive. (Find names [here](https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Material.html))
   * **Example:** `nether_star`, `DIAMOND`, `glowstone_dust`
   * **Default:** `"NETHER_STAR"` (If omitted or invalid)
2. name
   * **Type:** `String`
   * **Description:** The display name shown for the item in-game. Supports standard Bukkit color codes using `&`.
   * **Example:** `"&e&lShooting Star"`
   * **Default:** `"&bFalling Star"` (If omitted)
3. lore
   * **Type:** `List of Strings`
   * **Description:** The descriptive lines (lore) appearing below the item's name. Supports `&` color codes.
   * **Example:**YAML

     ```
     lore:
       - "&7A fragment from the sky."
       - "&eMake a wish!"
     ```
   * **Default:** `[]` (Empty list - no lore if omitted)
4. particles
   * **Type:** `String`
   * **Description:** The Bukkit Particle type for the trail effect while falling. Names are case-insensitive. (Find names [here](https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Particle.html))
   * **Example:** `flame`, `GLOW`, `soul_fire_flame`
   * **Default:** `"FLAME"` (If omitted or invalid)
5. sound
   * **Type:** `String`
   * **Description:** The Bukkit Sound name played repeatedly while falling. Names are case-insensitive. (Find names [here](https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Sound.html))
   * **Example:** `entity.firework_rocket.launch`, `BLOCK_AMETHYST_BLOCK_BREAK`
   * **Default:** `"ENTITY_FIREWORK_ROCKET_LAUNCH"` (If omitted or invalid)
6. probability
   * **Type:** `Number` (Double)
   * **Description:** Controls the chance of this star spawning automatically per player during each check cycle (defined in `config.yml`). The internal check compares `(random_number_0_to_1 * 10)` against this value; if the random number is lower, the spawn attempt passes. Higher values mean a higher chance. A value of 0 means it never spawns automatically.
   * **Example:** `0.1` (approx 1% chance per cycle), `1.5` (approx 15% chance per cycle)
   * **Default:** `0.0` (If omitted)
7. altitude
   * **Type:** `String` (Format: `"min-max"`)
   * **Description:** The range of blocks above the determined ground/surface location where the star will initially spawn. If min and max are the same, it spawns at a fixed relative height.
   * **Example:** `"30-70"`, `"50-50"`
   * **Default:** `"25-50"` (If omitted or invalid format)
8. sky
   * **Type:** `Boolean` (`true` or `false`)
   * **Description:** If `true`, the star will only spawn automatically if the block chosen on the ground has direct access to the sky (no solid blocks above it up to the world height limit).
   * **Default:** `false` (If omitted)
9. time
   * **Type:** `String`
   * **Description:** Determines when this star can spawn automatically based on the world time. Options are `"night"`, `"day"`, or `"any"`. Case-insensitive.
   * **Example:** `day`, `Night`, `ANY`
   * **Default:** `"night"` (If omitted or invalid)
10. world
    * **Type:** `String`
    * **Description:** The exact name of the world where this star type is allowed to spawn automatically via the background task.
    * **Example:** `world_nether`, `survival_world`
    * **Default:** `"world"` (If omitted)
11. explosion
    * **Type:** `Number` (Double/Integer) or `String`
    * **Description:** Defines the explosion behavior upon impact.
      * **Number (e.g., `3.5`):** Creates a real explosion with the specified power (TNT=4.0 is a reference). Damages entities. Whether it breaks blocks depends on `damage_blocks` and WorldGuard rules.
      * **String `"fake"`:** Creates only visual (particles) and sound effects of an explosion. Causes no damage or block breaking.
      * **String `"false"` or Number `0`:** No explosion effect occurs at all.
    * **Default:** Behaves like `"fake"` if omitted or the value is invalid.
12. damage\_blocks
    * **Type:** `Boolean` (`true` or `false`)
    * **Description:** Only effective if `explosion` is set to a positive number. If `true`, the real explosion will attempt to break blocks. This respects WorldGuard rules based on the flag configured in `config.yml` (`settings.worldguard.explosion-check-flag`).
    * **Default:** `false` (If omitted)
13. damage
    * **Type:** `Number` (Double)
    * **Description:** Extra damage (in half-hearts) dealt directly to entities within the radius defined by `settings.impact.damage-radius` in `config.yml`. This damage is applied *in addition* to any damage caused by a real explosion effect.
    * **Example:** `5.0` (deals 2.5 hearts of direct damage)
    * **Default:** `0.0` (If omitted)
14. remove\_item\_on\_impact
    * **Type:** `Boolean` (`true` or `false`)
    * **Description:** If `true`, the star item entity itself disappears upon impact after effects are triggered. If `false`, the item entity remains (or is re-dropped) on the ground after impact effects, allowing players to pick it up.
    * **Default:** `true` (If omitted)