Configuration reference
This is the config.yml HudForge writes on first start, comments included. Every key you see here is the key the plugin reads; there are no hidden ones. Change a value, reload, and it applies.
Top-level sections: refresh-ticks, nametag-refresh-ticks, default-profile, metrics-id, resource-pack, images, components, animations, profiles.
# HudForge — sidebar, tablist, nametags and bars, all in one file.
#
# Everything you write here accepts:
# · Gradients <gradient:#C879FF:#7A4DFF>TEXT</gradient>
# · ANIMATED gradient <shine:#C879FF:#FFFFFF:1800>TEXT</shine> (third number = cycle in ms)
# · Legacy colours &b&lTEXT
# · Built-in values %hud_player% %hud_ping% %hud_tps% %hud_online% %hud_max%
# %hud_world% %hud_x% %hud_y% %hud_z% %hud_health%
# %hud_protocol% (the CLIENT's protocol through ViaVersion: 47 = 1.8)
# · Resource-pack logo <lang_or:my.pack.key:TEXT> (pack players see the key's glyph, the
# rest see TEXT; old clients get the key: gate it on %hud_protocol%)
# · Pictures <img:logo> (a .png from plugins/HudForge/images, sent to players as a
# glyph of a pack this plugin builds; see resource-pack: below)
# · Rank values %hud_prefix% %hud_suffix% %hud_group% (LuckPerms, or any permissions
# plugin behind Vault's chat service; left as-is when there is none)
# · Money %hud_balance% (needs a Vault economy)
# · Switches %hud_economy% %hud_ranks% %hud_papi% (true/false: is that plugin there?)
# · Anything from any plugin, when PlaceholderAPI is installed
# · Conditions %if:%hud_ping%>150?<red>high:<green>good%
# · Math <math:%hud_health%*5> <math:(660/100)*%player_level_percent%:1>
# + - * / % ( ) min max round floor ceil abs; the last number = decimals
# · Bars <bar:%hud_health%:20:10> value : max : width [: filled : empty
# : colour-on : colour-off] → ▰▰▰▰▰▰▰▱▱▱, the width following the value
# · Components <use:stat:label=Kills:value=%df_kills%> (defined under components:)
# · Frame animations <anim:name> (defined below, frame by frame)
#
# A sidebar line, a TAB line or a boss bar can carry a condition and only show when it holds:
# - text: "<#C879FF>❙ <white>Faction <gray>%df_faction_name%"
# when: "%df_faction_name%!=none"
# The line is left out when the condition fails, and the lines below move up.
#
# How often the display is repainted. Animations need several repaints per second to look
# smooth: 4 ticks = 5 times per second, and it stays cheap because only the team prefixes are
# rewritten — the scoreboard itself is never rebuilt, which is what makes other plugins flicker.
refresh-ticks: 4
# How often the name above the head and the TAB order are rewritten. It is separate from
# refresh-ticks and much slower on purpose: that team has to be written into EVERY player's
# scoreboard, so it is the one thing here that costs more the fuller the server is. It is also
# rewritten immediately when someone joins, leaves or changes world, so 40 ticks (2 seconds) is
# only the safety net for a prefix that changed on its own (a rank-up, a timed permission).
nametag-refresh-ticks: 40
default-profile: default
# Anonymous usage statistics (bStats): how many servers run this plugin and on what version.
# 0 turns them off. There is also a global switch in plugins/bStats/config.yml.
metrics-id: 34181
# Pictures in the HUD. Drop .png files into plugins/HudForge/images and write <img:name> (the
# file name without .png, lower case) anywhere: a logo in the TAB header, an icon before a
# sidebar line, a badge in a boss bar. The plugin builds a resource pack where every picture is
# a glyph of its own font, and that pack reaches your players one of two ways:
# mode: self-host → this plugin serves the pack on `port` and sends it when a player joins.
# `host` must be the public address players connect to (IP or domain).
# Open the port in your firewall. The pack is ADDED on top of any pack the
# server already sends (1.20.3+), so it does not replace it.
# mode: export → the pack files are written into `export-to`, for the pack plugin you
# already run to merge them (ItemsAdder: plugins/ItemsAdder/contents/hudforge/
# resourcepack, then /ia zip; Nexo/Oraxen: their pack folder). Use this when
# another plugin already sends a pack and your clients are older than 1.20.3.
# mode: off → <img:...> prints nothing.
# A picture draws at `height` text pixels (8 = one line of text; 16 or 32 for a header logo) and
# sits `ascent` pixels above the baseline (height - 1 keeps it on the line). Per picture:
# images:
# logo: {height: 24, ascent: 20}
# Players on 1.8-1.20.2 clients cannot draw glyphs: gate the tag on %hud_protocol% as with
# <lang_or>. /hud images lists what was found and its glyph settings.
resource-pack:
mode: off
host: ""
port: 8140
prompt: ""
required: false
export-to: ""
description: "HudForge images"
images: {}
# Pieces you reuse. {name} is a parameter, {name=default} a parameter with a default. Parameters
# are split on ":", so a value with a colon in it (a condition) belongs in the component itself.
components:
stat: "<#C879FF>❙ <white>{label}"
value: "<#5B3A6E> <white>{value}<#5B3A6E> {unit=}"
# Frame animations, for what a plain gradient cannot do. The frame is picked from the clock, so
# every player sees the same frame at the same time.
animations:
# A dot of light travelling along the separator line.
separator:
interval-ms: 120
frames:
- "<#C879FF>▰<#5B3A6E>▱▱▱▱▱▱▱▱▱▱▱"
- "<#5B3A6E>▱<#C879FF>▰<#5B3A6E>▱▱▱▱▱▱▱▱▱▱"
- "<#5B3A6E>▱▱<#C879FF>▰<#5B3A6E>▱▱▱▱▱▱▱▱▱"
- "<#5B3A6E>▱▱▱<#C879FF>▰<#5B3A6E>▱▱▱▱▱▱▱▱"
- "<#5B3A6E>▱▱▱▱<#C879FF>▰<#5B3A6E>▱▱▱▱▱▱▱"
- "<#5B3A6E>▱▱▱▱▱<#C879FF>▰<#5B3A6E>▱▱▱▱▱▱"
- "<#5B3A6E>▱▱▱▱▱▱<#C879FF>▰<#5B3A6E>▱▱▱▱▱"
- "<#5B3A6E>▱▱▱▱▱▱▱<#C879FF>▰<#5B3A6E>▱▱▱▱"
- "<#5B3A6E>▱▱▱▱▱▱▱▱<#C879FF>▰<#5B3A6E>▱▱▱"
- "<#5B3A6E>▱▱▱▱▱▱▱▱▱<#C879FF>▰<#5B3A6E>▱▱"
- "<#5B3A6E>▱▱▱▱▱▱▱▱▱▱<#C879FF>▰<#5B3A6E>▱"
- "<#5B3A6E>▱▱▱▱▱▱▱▱▱▱▱<#C879FF>▰"
- "<#5B3A6E>▱▱▱▱▱▱▱▱▱▱<#C879FF>▰<#5B3A6E>▱"
- "<#5B3A6E>▱▱▱▱▱▱▱▱▱<#C879FF>▰<#5B3A6E>▱▱"
- "<#5B3A6E>▱▱▱▱▱▱▱▱<#C879FF>▰<#5B3A6E>▱▱▱"
- "<#5B3A6E>▱▱▱▱▱▱▱<#C879FF>▰<#5B3A6E>▱▱▱▱"
- "<#5B3A6E>▱▱▱▱▱▱<#C879FF>▰<#5B3A6E>▱▱▱▱▱"
- "<#5B3A6E>▱▱▱▱▱<#C879FF>▰<#5B3A6E>▱▱▱▱▱▱"
- "<#5B3A6E>▱▱▱▱<#C879FF>▰<#5B3A6E>▱▱▱▱▱▱▱"
- "<#5B3A6E>▱▱▱<#C879FF>▰<#5B3A6E>▱▱▱▱▱▱▱▱"
- "<#5B3A6E>▱▱<#C879FF>▰<#5B3A6E>▱▱▱▱▱▱▱▱▱"
- "<#5B3A6E>▱<#C879FF>▰<#5B3A6E>▱▱▱▱▱▱▱▱▱▱"
# The studio diamond, breathing.
diamond:
interval-ms: 420
frames: ["<#C879FF>◈", "<#E3BBFF>◈", "<#FFFFFF>◈", "<#E3BBFF>◈"]
# Profiles are tried IN ORDER and the first match wins, so put the specific ones first.
# A profile matches when the player is in one of its worlds, has its permission and its
# condition is true. Anything you leave empty is not checked.
# /hud open <profile> [player|*] [seconds] forces one onto a player for a while (an event
# screen, a countdown); /hud close puts the automatic choice back.
profiles:
default:
worlds: []
permission: ""
condition: ""
weight: 500 # tablist order: lower goes higher up the list
sidebar:
title: "<anim:diamond> <shine:#C879FF:#FFFFFF:1600><bold>TTS-STUDIO</bold></shine> <anim:diamond>"
# How the sidebar comes in when a player joins: reveal = the lines appear one after
# another over duration-ms, after delay-ticks. Remove the section to show it at once.
intro:
effect: reveal
duration-ms: 900
delay-ticks: 10
lines:
- "<anim:separator>"
- "<use:stat:label=%hud_player%>"
- "<#5B3A6E> %hud_world% <#3D2A4A>· <#5B3A6E>%hud_x%, %hud_y%, %hud_z%"
- ""
- "<use:stat:label=Health>"
- "<#5B3A6E> <bar:%hud_health%:20:10:▰:▱:#6BFF9E:#5B3A6E> <white>%hud_health%<#5B3A6E>/20"
- ""
- "<use:stat:label=Online>"
- "<#5B3A6E> <white>%hud_online%<#5B3A6E>/%hud_max% players"
- ""
- "<use:stat:label=Connection>"
- "<#5B3A6E> ping %if:%hud_ping%>150?<#FF6B6B>%hud_ping%ms:<#6BFF9E>%hud_ping%ms%<#5B3A6E> · tps <white>%hud_tps%"
# Only for players with a Vault economy behind them: no plugin, no line.
- text: "<#5B3A6E> money <white>%hud_balance%"
when: "%hud_economy%"
- "<anim:separator>"
- "<shine:#7A4DFF:#C879FF:2400>docs.tiamatmc.net</shine>"
tablist:
# The name each player is listed with in the TAB. Leave it out and the plain name is used.
name: "<#C879FF>◈ <white>%hud_player%"
header:
- ""
- "<anim:diamond> <shine:#C879FF:#FFFFFF:1600><bold>T T S - S T U D I O</bold></shine> <anim:diamond>"
- "<#5B3A6E>the plugin suite, live"
- ""
footer:
- ""
- "<#5B3A6E>tps <white>%hud_tps%<#5B3A6E> · your ping <white>%hud_ping%ms<#5B3A6E> · %hud_online% online"
- "<shine:#7A4DFF:#C879FF:2400>docs.tiamatmc.net/discord</shine>"
- ""
nametag:
prefix: "<#C879FF>◈ <white>"
suffix: ""
# The action bar sits over the hotbar, where the game also writes item names: for a second
# after you switch an item, the item name wins and this readout is hidden. Set it to "" to
# turn it off, or add %hud_balance% if you run a Vault economy.
actionbar: "<#5B3A6E>♥ <white>%hud_health%<#5B3A6E> · tps <white>%hud_tps%<#5B3A6E> · <white>%hud_online%<#5B3A6E> online"
# Boss bars. One entry per bar; the key is its id, and reusing the id updates that same bar
# instead of stacking a new one. Leave the section out and no bar is shown.
# color: PINK | BLUE | RED | GREEN | YELLOW | PURPLE | WHITE
# style: PROGRESS | NOTCHED_6 | NOTCHED_10 | NOTCHED_12 | NOTCHED_20
# progress: 0.0 to 1.0, a placeholder, or a formula: "%hud_health%/20"
# when: a condition; the bar only shows while it holds (optional)
bossbars:
welcome:
text: "<shine:#C879FF:#FFFFFF:1600>TTS-STUDIO</shine> <#5B3A6E>· <white>20 plugins, live"
color: PURPLE
style: PROGRESS
progress: "1.0"
low-health:
text: "<red><bold>Low health!</bold> <white>%hud_health%/20"
color: RED
style: NOTCHED_10
progress: "%hud_health%/20"
when: "%hud_health%<=6"