Pages

Supplemental Information/Frequently Asked Questions (FAQ)

1. How do I install the plugin?

First, download one of the plugin JAR from the Files tab at the top of this project page. (Be sure to select a version that supports your server version)

Then, on your craftbukkit/spigot/paper server, copy the JAR file into the plugins directory.(Be sure to remove any older versions of the plugin)

 

When you restart your server, the plugin will be loaded and a PlayerHeads folder with the configuration file (config.yml) which will be automatically created for you with default settings.

 

2. I'm getting a compatibility error, what should I do?

First, make sure the version of your server is supported by the plugin version you downloaded. Keep in mind that recent versions of the plugin do not support servers lower than 1.8, and cutting-edge server versions may not be fully supported yet by the plugin.

 

If you think the error is still due to a PlayerHeads bug, please create an issue on the Issue Tracker link above and include your full log file, list of plugins, server type and version, etc.  Keep in mind that the more plugins you have installed, the more difficult it will be to find the problem - you are encouraged to reproduce the problem with as few plugins as possible.

 

This page on older versions, and Glowstone servers may be useful to you.

 

3. How do I let players view head information when clicking heads, or prevent it?

To enable this feature, you must ensure players have the playerheads.clickinfo permission set to true (or allow, depending on your permissions plugin).  Keep in mind that even with this permission, protection plugins that disable "interactions" may prevent this feature from working.

 

Permissions are controlled by your installed permissions plugin, or by the server's Permissions.yml file when the server is loaded.

 

If you want to prevent the message from appearing, then you must deny (or negate) the permission mentioned above for the user or group you don't want to see the message.

 

4. Heads aren't dropping, what can I do?

Firstly, ensure heads have permission to drop.  For player heads to drop, the players losing their head need to have playerheads.canlosehead permission (enabled by default) and player-killers need the playerheads.canbehead permission to behead another player.  Similarly, players can only behead mobs if they have the playerheads.canbeheadmob permission.

Whether mobs can behead anything depend on the pkonly and mobpkonly configuration settings.

 

Next, ensure the droprate for heads allows them to drop, the value of droprate or droprate control individual heads drop rates (eg: 0.02 = 2% chance of dropping on each allowed kill).

 

Finally, if heads still aren't dropping, you should look at which protection plugins you use, plugins that force keep-inventory or deathchest may interfere with how PlayerHeads drops heads. In these cases, try changing the antideathchest configuration setting.  When this is true, PlayerHeads will tell Bukkit to force the item to drop near the death location, instead of adding the item to the player's dropped item list.

 

5. When spawning or placing a new head for a Player, there is sometimes a noticable delay

 

Note: this issue may be noticeably more pronounced on 1.14+ servers as opposed to 1.13.2 servers - however, this has not be independently confirmed as of yet.

 

When a head is spawned for a player, a head with the username is created without a texture. When Craftbukkit (or Spigot, etc) encounters one of these heads, it automatically requests the skin information from the Mojang server.

 

These requests are not easily prevented, modified, or performed early by plugins and you will notice the same delay when using major plugins like EssentialsX (with /skull ).   I'm sorry to say there's no easy fix for this issue.

 

A not-so-easy fix would be for the plugin to request skin information earlier through the Authlib library, but this comes with certain problems. First, it may increase the number of frequests and get the server rate-limited. Second, it needs to access certain internal variables of heads which can change and break the plugin between versions more easily. Thirdly, updating the head information outside of the API with NMS code is not actively supported or recommended on any Bukkit implementation - Authlib is not available at all on some servers, and there is an existing standard skin-retrieval mechanism that should be improved instead.

 

For these reasons, issues relating to this may be closed as WontFix.

 

6. Head skins are not updating for Player heads.

User profile information is cached at the server side, and skins are cached at the client side. While it's possible to clear these caches individually, it's recommended instead that you wait a couple hours for them to expire. Try re-spawning or breaking-and-replacing the head after an hour or two (and after the subject user leaves and rejoins the server).

 

If a newly spawned head has the same older skin, then it is most-likely due to one of these caching mechanisms that are outside of the control of the plugin.

 

7. How do I remove part or all of the loretext (description) from PH-created heads?

By default there are a couple of lines of loretext that appear in the item description (the name of the plugin and the head type).

If you want to disable all of these features, you should set the addlore configuration setting to false which will prevent any loretext from being added.

If you just want to disable part of the loretext, you should open your respective lang.properties (or the file with the relevant language code in the filename) file in the same configuration directory (plugins/PlayerHeads/).

There you can find the following options controlling how these lines appear:

  • LORE_PLUGIN_NAME=...
  • LORE_HEAD_MOB=...
  • LORE_HEAD_PLAYER=...

If you set any of these entries to blank (no spaces) on the righthand side, they should not be added to the loretext of the head - this may require a reload.

Keep in mind that if you have an older lang file, these lines may need to be added if they are not present.

8. How do I disable head drops in a specific area or region?

This is not a behavior that is available in PlayerHeads, however, if you are using WorldGuard 7+, there is an addon plugin called WGTrophyFlags which adds a flag for blocking PlayerHeads head-drops inside a region.

 

9. Heads are always dropping for me, how do I disable this?

Try denying (or "negating") the permissions (playerheads.alwaysbehead, etc) for a group all of your staff (or users with the problem) are in. You should be able to do this with your permissions plugin or with permissions.yml

 

 

How you do this depends on what you use to manage permissions:

With permissions.yml (bukkit default), you have to add the permission to your group with a value of false.
With some plugins, you instead add a permission with a dash in front (without a space, as part of the name) to negate the permission.
If you use something like LuckPerms, it should be as easy as (instead) setting the permission to deny rather than allow.

This means you will need to add a group to your existing staff, though.

 

In addition:

The plugin does not actually specify that the alwaysbehead permission should be given to ops, the default state is 'false' (those permissions should not be given to anyone automatically).
However if your staff were given playerheads.* wildcard permission then they will get that permission also, so that's something to avoid.

 

10. More than one head drops, how can I fix this?

This is usually a conflict with some other plugin.  

 

There are potentially a few different causes for this, but the most common setting that *could* cause this for some users is the "pretestblockbreak" configuration setting which you may need to disable or enable it to prevent duplicate heads. (it is enabled by default)

Use /ph config set pretestblockbreak false or true

 

For NoCheatPlus and a couple other of after-the-fact protection plugins, this feature was required to prevent bypassing block protections.

The reason it may cause duplicate heads is it sends a "test" block break event to check if breaking is allowed [there were some edge cases the protection APIs did not capture].
Some plugins interpret this as a second valid blockbreak while also simulating the item drop behavior - causing two items to drop.
In the reverse case, using NCP without checking first would cause a head to drop before the plugin replaced the block after-the-fact.

 

You may also want to try changing the "fixdroppedheads" and "fixbrokenheads" settings which try to replace the item provided in drops.  In cases where another plugin blocks and replaces the drop, this could also cause a duplicate head.

 

(Troubleshooting) I have an issue that this page didn't cover or didn't help with.

In the case where you have an issue with the plugin that isn't covered, there are some things you should do to try to track down the problem.

 

First, test the plugin on a server (you can run your own private spigot server for testing quite easily) with as few plugins as possible. The more plugins you have, the more difficult it will be to determine the cause.
A good strategy is to start a server with no plugins and configure PlayerHeads to work how you want and to slowly add other plugins until the problem reappears.

If you determine which plugin is incompatible, you may want to request a feature to support it - skip to the Request a Feature section below.

If you have the issue with no other plugins, continue troubleshooting as below.

 

Second, review the relevant documentation - you may be encountering a behavior that you can easily change:

If none of the options seem relevant, you may want report the problem (skip to Reporting an Issue)

 

Requesting a Feature

Create a new issue on one of the following links:

Be sure to clearly explain your feature and why it is not covered by existing options.

Features like shops and things that add large mechanics which could be handled by another addon-plugin may be considered out-of-scope. Remember that a goal is to keep the plugin simple but allow extension by other plugins - feature requests that are closer to core functionality are more likely to be added.

 

Reporting an Issue

Create a new issue on one of the following links:

Be sure that you are using the most recent version of the plugin and server

Be sure to include the following information:

  • Clear description of the issue and what you were doing when it happened.
  • Server type and version
  • List of plugins
  • Server log file with relevant messages, if they appear

If you submit an issue without proper information, it may be closed as invalid.

If you submit an issue with a long list of plugins, it may be very difficult to determine the cause of your problem or your issue may be ignored - please put some effort into reducing the number of plugins you use, but keep in mind that we can't solve every plugin conflict problem.