> For the complete documentation index, see [llms.txt](https://krystalfox-studio.gitbook.io/home/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://krystalfox-studio.gitbook.io/home/plugins/shootingstars/stars.yml.md).

# 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`
2. name
   * **Type:** `String`
   * **Description:** The display name shown for the item in-game. Supports standard Bukkit color codes using `&`.
   * **Example:** `"&e&lShooting Star"`
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`
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`
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)
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"`
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).
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.
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`).
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)
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)

15\. item\_model

* **Type:** `String`
* **Description:** if set, allows you to define a custom texture for the item, if you have a texture pack.
* **Example:** `"my_texture_pack:shining_star"`

16. **pdc**

* **Type:** `String`
* **Description:** If set, it allows you to configure an identifier for the item through a persistent data container tag, so you can identify it with other external plugins
* **Example:** `"my_server:epic_star"`