# Commands and permissions

## Commands

The base command for the plugin is `/sh` or its alias `/shootingstar`.

* **`/sh reload`**
  * **Description:** Reloads both the `config.yml` (global settings) and `stars.yml` (star definitions) files from disk. This applies any changes made to the files and restarts the automatic spawning task with the updated settings.
  * **Permission:** `shootingstar.reload`
* **`/sh spawn <star_name> [<player> | <x> <y> <z> [world]]`**
  * **Description:** Manually spawns a single star of the specified type at a target location.
  * **Arguments:**
    * `<star_name>`: (Required) The name of the star type as defined in `stars.yml`. This is case-insensitive.
    * `[<player>]`: (Optional) If provided, the star will spawn above a random surface location near this online player.
    * `[<x> <y> <z>]`: (Optional) If provided instead of a player name, the star will spawn centered above these exact coordinates. The star will appear higher based on its configured `altitude`.
    * `[<world>]`: (Optional, only used with coordinates) The name of the world where the coordinates apply. If omitted when using coordinates, it defaults to the sender's world (if the sender is a player). Console *must* specify a world when using coordinates.
  * **Behavior:** If no player or coordinates are specified, the command attempts to spawn the star near the command sender (requires sender to be a Player). If run from the console, either a player name or coordinates (with world name if needed) must be provided.
  * **Permission:** `shootingstar.command.spawn`
* **`/sh starfall <star_names> <amount> [<player> | <x> <y> <z> [world]]`**
  * **Description:** Starts a "starfall" event, spawning a specified number of stars randomly around a central location over time. Only one starfall event controlled by this command can be active globally at any time; starting a new one will stop the previous one.
  * **Arguments:**
    * `<star_names>`: (Required) One or more star type names (as defined in `stars.yml`), separated by commas **without spaces** (e.g., `ShootingStar,Meteor,RareStar`). The starfall will randomly pick from these types for each star spawned. Case-insensitive.
    * `<amount>`: (Required) The total number of stars to spawn during this event. Must be a positive whole number.
    * `[<player>]`: (Optional) The center point for the starfall will be this online player's location.
    * `[<x> <y> <z>]`: (Optional) The center point for the starfall will be these exact coordinates.
    * `[<world>]`: (Optional, only used with coordinates) The name of the world for the coordinates. Defaults to the sender's world if applicable, otherwise required for console.
  * **Behavior:** If no player or coordinates are specified, the starfall centers on the command sender (if player). Console requires a target. Stars spawn one by one according to `settings.starfall.interval-ticks`, scattered randomly within the horizontal `settings.starfall.radius` around the center point.
  * **Permission:** `shootingstar.command.starfall`
* **`/sh starfall stop`**
  * **Description:** Immediately stops any starfall event currently running that was initiated by the `/sh starfall` command.
  * **Permission:** `shootingstar.command.starfall`
* **`/sh help`** or **`/sh ?`** (or just `/sh`)
  * **Description:** Displays a basic help message listing the available subcommands.
  * **Permission:** None (Accessible by everyone by default)

## Permissions

These are the permission nodes used by ShootingStar to control access to commands. Use a permissions plugin (like LuckPerms, etc.) to grant these to players or groups.

* **`shootingstar.reload`**
  * **Grants:** Access to the `/sh reload` command.
  * **Default:** `OP`
* **`shootingstar.command.spawn`**
  * **Grants:** Access to the `/sh spawn` command.
  * **Default:** `OP`
* **`shootingstar.command.starfall`**
  * **Grants:** Access to the `/sh starfall <...>` and `/sh starfall stop` commands.
  * **Default:** `OP`
* **`shootingstar.command.*`**
  * **Grants:** Access to *all* current ShootingStar commands (`reload`, `spawn`, `starfall`). Useful for moderators or admins managing the plugin's commands.
  * **Default:** `OP`
  * **Child Nodes:** Includes `shootingstar.reload`, `shootingstar.command.spawn`, `shootingstar.command.starfall`.
* **`shootingstar.*`**
  * **Grants:** Access to *all* current and future ShootingStar permissions, including all commands. Recommended for server administrators.
  * **Default:** `OP`
  * **Child Nodes:** Includes `shootingstar.command.*` (and potentially other permissions added in the future).

*(**Note:** Default `OP` means only server operators have these permissions unless explicitly granted via a permissions plugin).*