EpicKnarvik97
353366559f
All checks were successful
KnarCraft/Minstrel/pipeline/head This commit looks good
64 lines
4.2 KiB
Markdown
64 lines
4.2 KiB
Markdown
# 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. |