CustomNameplates Update: Version 2.4 to 3.0 Overview
Last updated
Last updated
The CustomNameplates plugin has received a major update, drawing inspiration from the text display feature introduced in Minecraft 1.19.4+. This article will detail all the updates from version 2.4 to 3.0, covering bug fixes and performance optimizations from previous versions.
Built-in Placeholder System:
The plugin no longer has a hard dependency on PlaceholderAPI. It now includes a built-in placeholder parsing system, which is faster and more efficient. All built-in placeholders start with %np_, while expansion placeholders from PlaceholderAPI start with %nameplates_. Using the built-in placeholders provides a noticeable performance boost compared to PlaceholderAPI, making the parsing process significantly faster!
In the 2.x versions, the plugin introduced the refresh-interval and check-interval options to reduce the resource consumption caused by condition and variable parsing. Although these options reduced update frequency and improved performance to some extent, the complex parsing process still resulted in repeated parsing of the same conditions and variables.
In version 3.0, CustomNameplates' performance now depends only on the types of variables used and the refresh interval. This means that even if the same variable or condition is used multiple times, the plugin only updates it once, greatly reducing the resource consumption caused by repeated parsing. If you’re interested in how this optimization was achieved, you can check the source code on GitHub, which includes a complex pre-parsing system.
Three new configuration options have been added to config.yml to better manage parsing frequency:
default-condition-refresh-interval (Default condition parsing interval)
default-placeholder-refresh-interval (Default placeholder parsing interval)
placeholder-refresh-interval (Custom parsing interval for specific variables)
These intervals are measured in game ticks (50ms per tick). With these configurations, users can assign longer parsing intervals to performance-heavy variables, such as JavaScript-based variables, to reduce server load.
For conditions, the configuration is set up as shown in the example below (using refresh-interval):
The new version supports dynamic adjustment of parsing intervals based on the context in which the conditions are used:
Handling Same Conditions with Different Refresh Intervals: If the same condition is used in multiple places with different refresh intervals, the plugin will dynamically adjust the parsing based on demand. For example, if a condition is used in a BossBar display with a refresh interval of 10, and in conditional-text with an interval of 5, the plugin will first parse the condition with an interval of 10 but adjust it to 5 when parsing conditional-text.
In version 3.0, the method for calculating character advance has become more precise, aligning with the latest Minecraft client updates. The font-width-data.yml file has been renamed to advance-data.yml, and a large new configuration section, font-templates, has been added to config.yml to manage the various character types provided by Minecraft Font Providers
Font Configuration Options:
file: Refers to a file located in the /CustomNameplates/font directory.
custom: Specifies whether to use the default PNG bitmap font provided by the client.
generate: Indicates whether to include a copy of this font in the generated resource pack.
These options allow you to customize fonts used within the plugin and manage how and where they are sourced or generated.
All generated font advance data will be temporarily stored in the /CustomNameplates/tmp folder, speeding up subsequent server startups by preventing the need to recalculate font data each time. This caching mechanism improves startup performance.
Due to the increasing complexity of modern fonts, a single descent parameter is no longer sufficient. Therefore, descent-text has been renamed to shift-text. (%nameplates_descent_xxx% -> %np_shift_xxx%) This change also allows some configurations to use only the necessary subsets of fonts. For example, action bars displaying gold values might only use the ASCII character set, reducing unnecessary font set loading, which in turn minimizes the resource pack size and improves client performance.
Shift-Text Format Example:
The font field must be registered in the shift-fonts section in config.yml. For example:
The colon : followed by a number represents an offset value used to adjust the position of characters.
For bitmap fonts, the larger the number, the higher the y. For TrueType fonts (TTF), the larger the number, the lower the y.
In previous versions, creating multiple Unicode-supported descent-text instances resulted in redundant font width data being cached, each copy containing over 50,000 characters. In version 3.0, however, creating multiple shift-text instances will no longer increase memory usage, eliminating redundant data storage and improving memory management.
In previous versions, users manually input the width parameter to set the character width, often leading to inaccurate results. In the new version, the plugin adopts the same calculation method as the client, automatically calculating the advance for added characters. As a result, the width option has been deprecated, simplifying the process and improving accuracy.
The new version has removed the display name and text format configurations from the bubble settings. These options have now been moved to /configs/bubble.yml to accommodate the new multi-line bubble feature. This change allows for better organization and more flexibility in customizing bubbles in line with the updated system.
You’ll notice that the plugin registers a font called shift_0, which has no offset. This is due to a special client option called "Force Unicode Font." When users enable this option, they see thinner fonts, causing issues with alignment between nameplates, backgrounds, bubbles, and text. To address this, the plugin registers the shift_0 font to ensure that the client and server font advance data are synchronized, forcing the fonts to align properly. This guarantees that the plugin's final visual effect matches the intended design, even when Unicode fonts are used.
In previous versions, left-margin and right-margin were part of the background configuration. In version 3.0, these options have been moved to background-text. Additionally, the concept of margins has been introduced into nameplate-text, allowing users to more flexibly configure margins for nameplates.
You'll notice that the previous remove-shadow: true option has now been changed to shadow: false. This is due to the new version using the updated color code <#F0F0F0> to remove shadows, which works differently from the old version, particularly in how it handles semi-transparent images. If you continue to use remove-shadow, it will apply the old version's color code. You don't need to change this option if you're comfortable with the previous behavior.
The new version removes the player name color option in nameplates and replaces it with customizable color prefixes via switch-text. This allows users to fully customize colors, including dynamic gradient colors, making nameplates more flexible and visually appealing.
Player tags are now displayed using text mounted directly on the player, eliminating the need for compatibility with team-based plugins. As a result, nameplates only need to be installed on the backend server, and all compatibility settings for team plugins have been removed from config.yml.
This method of mounting text display significantly reduces server bandwidth usage and performs better when players are riding other entities (e.g., boats or horses). Moreover, players can preview their nameplates instantly without any delay.
The shader has removed the old version’s code for offsetting entity name text and added a new method for removing shadows. At the same time, it retains the old shadow removal method for backward compatibility. This allows users to choose between the new and old shadow removal techniques, depending on their preferences or requirements.
