EpicKnarvik97
9fd25b90f7
Adds documentation for all commands to the README Adds option to force an update if changing the pitch or volume of a minstrel Adds tab-completions for removeSong, listSongs, volume and pitch commands Adds filtering for tab-completions based on current input
70 lines
4.2 KiB
Markdown
70 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.
|
|
|
|
Volume between 0 and 1 decides how loud the volume is. If volume is set above 1, it will still play at full volume, but
|
|
can be heard further away.
|
|
|
|
## 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 best one can do is track any time a song is played
|
|
outside the global cycle.
|
|
- When a new player joins there are only two ways to make the music play for the player: Either play immediately, and
|
|
cut the song short once the playlist switches songs, or play nothing until the playlist switches songs. None of these
|
|
are ideal.
|
|
- Songs are really only identified by the category and the song id. Stopping the song for one minstrel will also stop
|
|
the song if played by any other minstrels at the same time. As songs are only stopped if a song has been played for a
|
|
player outside the global cycle, it shouldn't be too much of a problem, but if several minstrels play the same song,
|
|
there may be silent minstrels until the next song plays.
|
|
|
|
## Commands
|
|
|
|
| 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. Set to 1 for full volume, 0.5 for half volume, etc. If set above 1, the
|
|
minstrel can be heard from farther away, while the actual volume will be the same as for 1.0 when close to the NPC.
|
|
- 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. |