CustomDamageNumbers: floating damage numbers drawn entirely with packets. Nothing is spawned into the world, the numbers follow the entity that took the hit, and every part of the animation is a value in config.yml.
Every damage-indicator plugin eventually leaves something behind: an armour stand that survived a chunk save, an entity that the plugin forgot to remove, a number frozen in the air after a mob walked away. This one does not, because it never puts anything in the world.
Packet-only rendering. Each number is a client-side display entity sent over the protocol with PacketEvents. No world state changes, so uninstalling leaves nothing behind — and there is no entity count to explain to your players.
Anchored to the victim. The number belongs to the entity that took the hit and is re-positioned every animation step, so a mob knocked backwards drags its number with it. follow-smoothing blends the anchor instead of snapping, which removes the jitter on fast targets.
Config-driven animation. Duration, rise, fall, bounce, orbit, scale, fade, spawn spread and anchor height are all live values. Edit, /cdn reload, watch it move — no restart.
Hit merging. Ten hits in half a second grow one number instead of stacking ten, with a configurable window, cap and attacker rule.
Player-dealt hits only. A number appears for damage a player dealt — melee, or their arrows and other projectiles. A mob hitting you, fall damage or a fire tick is deliberately not a damage number, which is what keeps a mob farm readable.
Players choose./cdn toggle switches numbers off for one player and persists across restarts; /cdn style picks a profile when their rank allows one.
Two jars, one codebase. A modern text-display renderer for 1.20.2 – 26.x and a legacy armour-stand renderer for 1.17.x – 1.20.1, behind a single RenderBackend interface. Compiled against the oldest supported API so a Paper-only class cannot leak in.
The modern jar refuses to enable on an older server and tells you which jar to use instead, rather than rendering nothing. The legacy jar also runs on modern servers, but the modern jar is better there (only TextDisplay can fade and scale per entity); its startup log says so. Run /cdn backend on a live server to see which one is active and what it supports.
? Requirements
Requirement
Minimum
Notes
Minecraft server
1.17.1
Spigot, Paper, Purpur, Pufferfish, Folia and their forks
Restart, then check the console banner and /cdn version. Every config value is read on /cdn reload, so nothing below needs a restart.
⌨️ Commands & Permissions
Command
What it does
Permission
Default
/cdn help
Framed command list, filtered to what you may use
–
–
/cdn version
Plugin, renderer and server panel
–
–
/cdn backend
Active renderer and its capabilities
–
–
/cdn stats
Live counters, viewer slots, tick cost
cdn.stats
op
/cdn toggle [on|off] [player]
Turn numbers on or off for yourself or another player
cdn.toggle / cdn.toggle.others
true / op
/cdn style [player] <profile|default>
Pick a style profile
cdn.style / cdn.style.others
true / op
/cdn test [type] [amount]
Spawn a test display, no damage needed
cdn.test
op
/cdn clear [player|all]
Remove live displays immediately
cdn.clear
op
/cdn reload [config|messages|all]
Reload configuration and/or messages
cdn.reload
op
/cdn debug [on|off]
Verbose logging
cdn.debug
op
Aliases: /damagedisplay on both jars, plus /damage on the legacy jar — the modern jar deliberately leaves /damage to vanilla, which gained its own command in 1.20.5. Style profiles are granted per player (cdn.style.fortnite defaults to true, cdn.style.mmo to false), so LuckPerms can hand one to a rank. cdn.view is only enforced when permissions.require-view-permission is true.
Every panel adapts to where it runs: players get the box-drawing frame, the console and RCON get an ASCII frame with colour codes stripped.
⚙️ Configuration
The shipped config.yml is commented in full. The parts people actually change:
general:
enabled: true # master switch
view-distance: 32 # max distance a player receives numbers from
disabled-worlds: [example_world]
entities: { mobs: true, players: true, animals: true }
max-active-displays: 2000 # flood protection for mob farms
default-view-enabled: true # what a player sees before /cdn toggle
animation:
preset: default # animation preset from presets.yml
# any key below overrides that single value of the chosen preset
#duration-ticks: 30 # total lifetime (20 ticks = 1s)
#rise-ticks: 10 # ticks rising before the sink starts
#vertical-speed: 0.08 # blocks per tick while rising
#scale-animation: true
#start-scale: 1.3
#end-scale: 0.8
#fade-out: true # modern jar only
#bounce: true
#follow-entity: true # the number stays on the damaged entity
#follow-smoothing: 0.35 # 0 = snap each tick, higher = softer
#position: { x: 0.0, y: 1.8, z: 0.0 }
#offset: { random: true, spread: 0.20 }
merge-system:
enabled: true
merge-window-ms: 150 # a follow-up hit inside this window grows the number
styles:
normal: { format: "{damage}", color: "#FFFFFF", bold: true, shadow: true }
critical: { format: "✧ {damage}", color: "#FF3333", bold: true, shadow: true }
healing: { format: "+{damage}", color: "#00FF99", bold: true, shadow: true }
style-profiles: # handed out with cdn.style.<name>
fortnite: { critical: { format: "{damage}", color: "#FFFF00" } }
mmo: { normal: { format: "{damage} DMG" }, critical: { format: "{damage} CRIT", color: "#FF5555" } }
critical-hits:
sound-type: entity.player.attack.crit # vanilla keys and Bukkit-style names both work
? API for developers
Other plugins can spawn damage numbers, restyle everything the plugin renders,
or manage per-player state. Add in.potenfyr:cdn-api:1.0.0 (built with
./gradlew :cdn-api:publishToMavenLocal) as a compileOnly dependency,
softdepend: [CustomDamageNumbers] in your plugin.yml, then:
CustomDamageNumbersApi api = CustomDamageNumbersApi.get().orElse(null);
if (api != null) {
api.spawn(api.numberBuilder()
.at(victim) // or .at(location) for a fixed anchor
.value(42.5)
.type("fire") // styles.<key>, or set .format(...)
.format("<gold>✦ {damage}") // MiniMessage or legacy codes
.preset("explosive") // animation preset from presets.yml
.critical(true));
}
Every builder option is optional: unspecified values fall back to the plugin
configuration, a preset overrides those per key, and explicit builder
settings win over everything. Listen to DamageNumberSpawnEvent to cancel or
restyle every number the plugin renders, including your own. See
cdn-api/src/main/java/in/potenfyr/cdn/api for the full surface.
Every string the plugin prints lives in messages.yml, including the frame: block (width, border, title, subtitle, label, value, accent, footer, glyph, bullet) — edit it once and both the chat panels and the console panels change.
? Compatibility Notes
Server
Jar
Status
1.17.x – 1.19.x
Legacy
verified end to end
1.20.1
Legacy
verified end to end
1.20.2 – 1.21.x
Modern
verified, including fade and scale
26.x (Paper)
Modern
verified; older clients connect through ViaVersion
Folia
either
folia-mode: auto selects the region scheduler
1.16.x is out of reach. Paper 1.16.5 refuses to run on Java 17 (Unsupported Java detected (61.0)), and the jars are Java 17 bytecode. The practical floor is 1.17.1.
ViaVersion, ViaBackwards, ViaRewind, Geyser, ProtocolLib and ProtocolSupport are soft dependencies: detected, never required.
Fade and per-entity scale need a TextDisplay. The legacy jar positions and drifts numbers but cannot fade them — that is the one behavioural difference between the jars.
? Building
The build is Gradle (cdn-core, cdn-modern, cdn-legacy) and runs in Docker, so no host toolchain is required:
That produces cdn-modern/build/libs/CustomDamageNumbers-<version>.jar (with kyori and bStats relocated) and cdn-legacy/build/libs/CustomDamageNumbers-Legacy-<version>.jar.
? Testing
docker run --rm -v "$PWD:/app" -w /app gradle:jdk17 gradle test --no-daemon
bash docker/e2e/run.sh # full matrix: 1.17.1, 1.20.1, 1.21.8, 26.3
bash docker/e2e/run.sh 1.21.8 # one version, for a fast loop
The unit suite (108 tests) covers config parsing, damage classification, merging, the preference store, the frame renderer and both renderers. The end-to-end harness boots a real Paper server per version in Docker, installs the built jar plus PacketEvents, and asserts the display is created, positioned, moved across the animation and destroyed — and that the plugin disables cleanly with no errors in the server log. Evidence lands in docker/e2e/evidence/.
? Releases
The plugin version is fixed at 1.0.0 and does not move per change. .github/workflows/release.yml publishes on every push to master: it builds and tests, reads the version from gradle.properties, merges a new Build N section (the commits since the previous build) into the release notes for that version, re-uploads both jars with --clobber and moves the v1.0.0 tag to the newest build. So v1.0.0 always carries the latest jar and an accumulating changelog, one entry per push.
? Contributing
PRs are welcome; see CONTRIBUTING.md for setup, commands and the non-negotiables. In short:
Packets, never entities — no code path may spawn a real entity into the world.
Compile against the oldest supported API; version-specific code belongs in a renderer, not core.
Behaviour changes come with a test; run the build and the relevant end-to-end version before pushing.
Found a vulnerability? Please report it privately: see SECURITY.md.
Licensed under the Apache License 2.0 with the Commons Clause: free to run, fork, modify and build on, including on a commercial server; not to be sold as a product. See LICENSE; the LICENSE file is authoritative. Minecraft and Mojang trademarks belong to Mojang; see NOTICE.md.
评论 0
登录后参与评分
还没有评论,来抢沙发吧