⚙️ config.yml

This file contains the global settings for LiteNameTags.

It controls update behavior, vanilla nametag handling, health updates, compatibility options, messages, and performance-related settings.

---

Overview

The config.yml file is divided into the following main sections:

• settings

• health-updates

• update-check

• compatibility

• messages

• performance

Each section affects a different part of the plugin, so it is recommended to start with the default values and only adjust what your server actually needs.

---

settings

This section controls the core behavior of the plugin.

update-interval

Defines how often the main update task runs.

• Lower values = smoother updates, but more CPU usage

• Higher values = less CPU usage, but slower updates

disable-default-nametag

Hides the vanilla nametag using the plugin's own scoreboard team handling.

This is the standard option if you want players to only see the LiteNameTags hologram.

force-disable-default-nametag

Uses a more aggressive approach to hide the vanilla nametag.

This can be useful if another plugin or setup keeps making the default nametag visible again.

show-current-nametag

If enabled, players can also see their own nametag above their head.

show-while-looking

If enabled, nametags are only shown when the viewer is looking at the target player.

This changes the normal visibility behavior and is usually left disabled.

remove-empty-lines

Removes lines that become empty after placeholder replacement.

This helps prevent blank spacing inside nametags.

update-on-health-change

Forces faster updates when a player's health changes.

Useful for health-based nametags, but may increase update load.

hide-vanilla-nametags

Another vanilla nametag hiding option.

In most cases, you should not stack too many nametag hiding options unless you actually need to.

---

health-updates

This section controls the optimized health update queue.

It is only relevant if health-based nametag updates are enabled.

Main options

• enabled enables the health update queue

• interval-ticks controls how often the queue is processed

• only-when-visible-value-changes avoids unnecessary updates if the displayed value does not change

• min-update-gap-ms prevents health metadata spam

• max-metadata-per-tick sets a safety limit for health metadata processing

This section is useful for PvP-heavy servers or any setup where health values are shown in nametags.

---

update-check

Controls whether LiteNameTags checks for new plugin versions.

If enabled, admins may receive update notifications when a new version is available.

---

compatibility

This section contains support settings for different platforms and plugins.

Bedrock

The bedrock section is used for Geyser and Floodgate related behavior.

It includes options for:

• enabling Bedrock-specific handling

• adding extra Y offset

• forcing legacy-only formatting

• stripping MiniMessage tags

• disabling obfuscated text

Disguises

The disguises section controls behavior when disguise plugins are involved.

It can hide nametags while a player is disguised and uses a cache for better performance.

HMCCosmetics

The hmccosmetics section adjusts nametag offsets when cosmetics such as helmets or backpacks affect the player's model.

---

messages

This section controls plugin messages shown through commands.

It includes:

• no permission messages

• help output

• reload confirmation

• command usage

• update check messages

You can customize these messages to better match your server's style.

---

performance

This is one of the most important sections in the file.

It controls how LiteNameTags behaves under load and how aggressively it sends updates.

Main options

max-metadata-packets-per-run

Limits how many metadata packets can be sent in one update cycle.

This helps protect Netty from large spikes.

max-players-per-run

Limits how many owner players are processed per cycle.

Setting this to 0 means all players are processed.

placeholder-cache-ttl-ms

Defines how long placeholder results stay cached.

Higher values reduce CPU usage but make updates less immediate.

nearby-density-cache-ttl-ms

Caches nearby player density checks used for crowd-mode decisions.

---

packet-queue

The packet-queue section controls packet throttling for spawn, destroy, and passenger packets.

This helps smooth out large bursts when many nametags are created, removed, or reattached at the same time.

Available limits

• spawn-per-tick

• destroy-per-tick

• passenger-per-tick

---

crowd-mode

The crowd-mode section is designed for high-density player areas such as spawn, warps, or PvP hubs.

When enabled, LiteNameTags can reduce update cost in crowded environments by limiting viewers, reducing update frequency, and forcing non-relational placeholders.

Main options

• nearby-radius

• threshold

• max-viewers-per-player

• update-every-runs

• force-non-relational

• view-distance-cap

This section is especially useful for large servers with heavy player clustering.

---