Minstrel/README.MD

# Minstrel

This plugin aims to add a Minstrel trait to Citizens NPCs which is able to play a set of songs from a custom resource
pack. While there are plugins which use workarounds, this plugin aims to make the best npc-based "music box" add-on one
can create within the Spigot API. While kind of hard to set up, this allows using any music, without compromise. Note:
To make music hear-able only within the area of an NPC, you must make sure the track is Mono (1 channel). If you use a
Stereo (2 channels) soundtrack, you'll hear the music everywhere, which is cool if you want to stream music globally.

## Dependencies

- Citizens

## Important to note

There are limitations connected to directly playing media using playSound:

- There is no way to really know what is playing for a player. The only thing used to track when a song is finished is
  the length provided when adding a song. Make sure it's correct.
- There is no way to know if a player has the server resource pack, and thus if they have custom songs. When resource
  pack songs play, players that rejected it will hear silence.

## Commands

To make a new minstrel, use `/npc select` to select the NPC, then use `/trait add Minstrel` to add the minstrel trait.

| Command              | Arguments                                                  | Description                                                                               |
|----------------------|------------------------------------------------------------|-------------------------------------------------------------------------------------------|
| /minstrel addSong    | \<sound category> \<sound identifier> \<duration>          | Adds the specified song to the selected minstrel's playlist                               |
| /minstrel removeSong | \<index (0-10000)>                                         | Removes the song at the given index from the selected minstrel's playlist                 |
| /minstrel listSongs  | none                                                       | Lists all songs in the selected NPC's playlist in the format CATEGORY:identifier:duration |
| /minstrel volume     | \<new volume (0.01 to 10000)> \[force update (true/false)] | Displays or sets the volume of the selected minstrel                                      |
| /minstrel pitch      | \<new pitch (0.01 to 10000)> \[force update (true/false)]  | Displays or sets the pitch of the selected minstrel                                       |

### /minstrel addSong

- sound category - The category to use when playing the song. This is used when playing the sound to decide which volume
  slider can be used to alter the volume. RECORDS is recommended for minstrels. You may also specify "null" as the sound
  category. It will then be played without a specific category being specified.
- sound identifier - The string used to identify the sound to play. Example: "minecraft:music_disc.cat" identifies the
  cat music disc. You can also specify music in a resource pack, though nothing can be heard for players without the
  resource pack.
- duration - The duration of the track, in seconds. It's important that this is exact, and not too short, as it's used
  to decide when to start playing the next track in the playlist. If it's too short, several songs will end up playing
  at once! Setting it higher than the actual duration can be used to add a pause before the next song is played.

Example: `/minstrel addsong RECORDS minecraft:music_disc.cat 185` would be used to add the CAT music disc to a playlist.

### /minstrel removeSong

- index - The 0-based index of the song's position in the playlist. Use `/minstrel listsongs` to see the current
  playlist.

Example: `/minstrel removesong 0` removes the first song in the playlist.

### /minstrel volume

- new volume - The new volume of the minstrel. Volume between 0 and 1 (0.1 = 10%) decides how loud the volume is. If
  volume is set above 1, it will still only play at full volume (100%), but can be heard further away.
- force update - Whether to forcefully stop and start the minstrel's playlist to make the change happen instantly.

### /minstrel pitch

- new pitch - The new pitch used by the minstrel. Set to 1 for normal.
- force update - Whether to forcefully stop and start the minstrel's playlist to make the change happen instantly.