BlacksmithVisuals/README.md

# Blacksmith Visuals

This plugin adds additional visual and audial details to blacksmiths while they are working, so it's easier to see if
they are working or not. It is recommended to put a mace or other hammer-like item in the NPC's off-hand for full
effect.

## Dependencies

This plugin requires the following:

- [Blacksmith](https://www.spigotmc.org/resources/blacksmith.105938/)
- [Citizens](https://www.spigotmc.org/resources/citizens.13811/) (also a dependency for Blacksmith)
- [ProtocolLib](https://www.spigotmc.org/resources/protocollib.1997/)

## Setting up a new NPC

While most things are automatic, you should set the NPC's idle and working locations for the NPC to automatically move
to the crafting station while working. Use `/setNPCPosition idle` to set the position the NPC will go to after it's
finished working. Use `/setNPCPosition reforging-workstation` to set the position the NPC will be in while working. As
scrappers can salvage lots of different things, they have two additional positions.
Use `/setNPCPosition netherite-workstation` to set the position the scrapper will use when working on netherite or
armor-trim items (smithing table). Use `/setNPCPosition crafting-workstation` if extended salvage is enabled to set the
position the NPC will use when working on extended salvage (crafting table).

Remember to disable lookclose or adjust it as described in the FAQ.

## FAQ

### Citizens lookclose makes NPC rotate weirdly and not face its crafting station

It has been found that with some options, lookclose can still be used. An example of a working lookclose setup is:
`/npc lookclose --linkedbody false --disablewhennavigating true --perplayer true --range 3 --targetnpcs false --headonly true --linkedbody false`
The value of realistic looking `/npc lookclose -r` may also affect behavior. Some other options might work as well, but
a lot of options won't, as it messes with manual NPC rotation. Keep that in mind.

### NPCs teleport part of the way while walking to or from a crafting station

This behavior is inevitable. As Citizens pathing is not very accurate (as described in Citizens' FAQ), the NPC must be
teleported when it's about to reach the destination to end up in the correct spot.

## Commands

| Command                                                    | Options                                                                  | Description                                                                                  |
|------------------------------------------------------------|--------------------------------------------------------------------------|----------------------------------------------------------------------------------------------|
| /reload (/blacksmithvisuals:reload)                        |                                                                          | Reloads the plugin.                                                                          |
| /setNPCPosition <positionType>                             | idle, netherite-workstation, reforging-workstation, crafting-workstation | Sets an idle or working position for an NPC to the current location of the executing player. |
| /playTestSound <sound category> <sound> \[volume] \[pitch] |                                                                          | Plays the specified sound at the selected NPC's location.                                    |

## Permissions

| Permission                      | Description                                  |
|---------------------------------|----------------------------------------------|
| blacksmithvisuals.*             | Gives all permissions.                       |
| blacksmithvisuals.reload        | Gives access to the reload command.          |
| blacksmithvisuals.setposition   | Gives access to the /setNPCPosition command. |
| blacksmithvisuals.playtestsound | Gives access to the /playTestSound command.  |

## Configuration

Each sound played can be disabled, or have
its [sound](https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Sound.html), [sound category](https://hub.spigotmc.org/javadocs/spigot/org/bukkit/SoundCategory.html),
pitch, volume and offset specified. The offset can be used to delay a sound to better time it with events happening at
the same time as the sound. The working sounds also support a negative offset which causes the working animation to be
delayed instead.

The sound category affects which volume slider players must use to decrease the volume of the sound.

The animation of the NPC's arm is triggered according to animationDelay. Then, based on animationChance, it might
trigger, or it might not trigger. If you for example want to have it animate on a set delay, you could set
animationChance to 100 and animationDelay to 20 to make it swing its arm once a second.

Use the reload command after you have altered the configuration. Note that changes won't happen for working sounds and
working animations for NPCs in the middle of working when the command is triggered.