Global Settings

Settings at the top level of config.yml that control general plugin behavior.

language

language: en

Specifies which language file to use. The file must be in plugins/HeadBlocks/language/ and named messages_xx.yml where xx is the language code.

metrics

metrics: true

Allows gathering anonymous usage statistics via bStats. You can safely disable this.

Reloading the plugin has no effect on this property. Restart the server to apply changes.

heads

heads:
  - 'default:Base64String'
  - 'hdb:Id'
  - 'player:PlayerName'

Head textures used when placing HeadBlocks. Three formats are available:

Format	Description
default:<base64>	Base64 encoded texture. Get the Value from Minecraft-Heads (Other section)
hdb:<id>	Head ID from HeadDatabase plugin
player:<name>	A player's name — uses their skin head texture

Skulls and BetterHeads plugins are not supported due to API incompatibility.

When using /hb give <playerName>:

• Add * to give all HeadBlocks

• Add a number to give the head at that position in the config

headsTheme

headsTheme:
  enabled: false
  selected: "Christmas"
  theme:
    Easter:
      - 'default:<base64>'
    Halloween:
      - 'default:<base64>'
    Christmas:
      - 'default:<base64>'
    Custom:
      - ''

Predefined themed texture lists. When enabled, overrides the heads config above. Each theme uses the same texture formats as heads.

Will not update already-placed heads.

progressBar

progressBar:
  totalBars: 100
  symbol: '|'
  notCompletedColor: '&7'
  completedColor: '&a'

Configures the progress bar displayed with the %progress% placeholder.

Option	Description
totalBars	Number of symbols displayed
symbol	Any character (|, ▮, etc.)
notCompletedColor	Color for incomplete portion
completedColor	Color for completed portion

Hex colors ({#ffffff}) and centering ({center}) are supported.

shouldResetPlayerData

shouldResetPlayerData: true

When true, player progress data is deleted when a head is removed (via command or sneak+click). Disabling this will cause unused data to accumulate in the database.

hideFoundHeads

hideFoundHeads: false

When enabled, heads a player has already found are hidden from their view using PacketEvents.

Known limitation: The server still maintains the physical block. Players will encounter an invisible collision box (forcefield effect) where hidden heads are located.

Requires PacketEvents and a server restart. Remember to disable the 'Found' hologram or leave the placeholder empty in advanced hologram mode.

preventCommandsOnTieredRewardsLevel

preventCommandsOnTieredRewardsLevel: false

When enabled, headClick commands are not executed if the player's current count matches a tieredRewards milestone. Only the milestone commands run.

preventMessagesOnTieredRewardsLevel

preventMessagesOnTieredRewardsLevel: false

When enabled, headClick messages are not sent if the player's current count matches a tieredRewards milestone. Only the milestone message is shown.

externalInteractions

externalInteractions:
  piston: true
  water: true
  explosion: true

Controls protection against external block interactions that could destroy heads.

Option	Description
piston	Prevent pistons from pushing/destroying heads
water	Prevent liquid flow from destroying heads
explosion	Prevent explosions from destroying heads

Disabling these options can improve performance, but heads will be vulnerable to the corresponding interactions.

placeholders

placeholders:
  leaderboard:
    prefix: ""
    suffix: ""
    nickname: false

Customizes the %headblocks_leaderboard_<position>_custom% placeholder. Supports PlaceholderAPI.

Option	Description
prefix	Text displayed before the player name
suffix	Text displayed after the player name
nickname	Use player nickname instead of username

Players must reconnect or the server must restart for changes to take effect.

See Placeholders Reference for the full list of available placeholders.

internalTask

internalTask:
  delay: 20
  hologramParticlePlayerViewDistance: 16

Controls the plugin's internal task scheduler.

Option	Description
delay	How often (in ticks) the plugin checks for nearby players around heads
hologramParticlePlayerViewDistance	Maximum distance at which players can see holograms and particles

Increasing the delay or reducing the view distance can improve performance.

gui

gui:
  borderIcon:
    type: GRAY_STAINED_GLASS_PANE
  previousIcon:
    type: ARROW
  nextIcon:
    type: ARROW
  backIcon:
    type: SPRUCE_DOOR
  closeIcon:
    type: BARRIER

Customizes the icons used in all plugin GUIs.

Icon	Default	Description
borderIcon	GRAY_STAINED_GLASS_PANE	Border/filler slots
previousIcon	ARROW	Previous page button
nextIcon	ARROW	Next page button
backIcon	SPRUCE_DOOR	Back to previous menu
closeIcon	BARRIER	Close menu button

Values must be valid Material names.