Add experimental Velocity plugin reload support by MrSimpleJS · Pull Request #95 · Test-Account666/PlugManX

MrSimpleJS · 2026-07-14T17:26:57Z

This PR adds experimental runtime plugin management for Velocity 3.4.0 through 4.1.0. Newer versions use the Velocity 4.x adapter after runtime capability checks.

PlugManX can now load, unload, enable, disable, restart, and reload compatible Velocity plugins without restarting the proxy.

Java 25 or newer is required. Velocity has no official runtime reload API, so this development build uses capability-checked internal APIs that may require updates when Velocity changes.

Features:

Runtime loading, unloading, enabling, disabling, restarting, and reloading
Support for Velocity 3.4.0 through 4.1.0
Version-specific adapters for Velocity 3.4+ and 4.x
Startup validation of required internal classes, fields, methods, and registries
Automatic capability checks for newer Velocity builds
Reload is disabled safely when required runtime internals are incompatible
Serialized operations to prevent concurrent registry and classloader changes
Dependency validation and dependency-aware bulk operation ordering
Plugin initialization and shutdown lifecycle event handling
Fault-tolerant cleanup that continues when individual steps fail
Cleanup of listeners, scheduled tasks, commands, messaging channels, registries, and classloaders
Classloader-aware packet registry cleanup
Packet registry snapshots and per-plugin registration delta tracking
Safe removal of exactly the packet mappings added during plugin initialization
Fallback cleanup for late or asynchronously registered packet mappings
Runtime validation of Velocity StateRegistry and packet registry layouts
Protection against duplicate packet registrations after reload
Tracking of plugin-owned messaging channels
Detection of remaining threads, registrations, classloaders, and other unload leaks
Detailed reporting of failed cleanup steps
Automatic rollback to the previous JAR when loading or reloading fails
Recovery from partial unload and cleanup failures
Protection for critical plugins with Velocity-only --force support
Console-only Velocity commands to prevent conflicts with backend PlugManX installations
Velocity-specific configuration, messages, help output, and plugin lists
Colored console output and development-build startup diagnostics
Reload timings and detailed diagnostics with velocityReloadDebug: true
Crash dumps with unique IDs for runtime and cleanup failures

Showcase:
https://www.youtube.com/watch?v=X3AOtK3jhPo

Download for Velocity:
PlugManX-3.0.5.Velocity.zip

I added experimental Velocity plugin loading, unloading, and reloading with runtime cleanup, platform-specific configuration and messages, startup warnings, detailed diagnostics, reload timings, and a separate versioned Velocity build.

Velocity unload cleanup fault-tolerant, added version-specific runtime adapters, and introduced debug leak detection for remaining listeners, tasks, commands, and plugin threads.

Test-Account666 · 2026-07-14T18:03:42Z

Wait, how's the disable command going to work?
Velocity doesn't really have that concept?

Test-Account666 · 2026-07-14T18:08:25Z

Nevermind, I see now.
Though... This could confuse users, no?

MrSimpleJS · 2026-07-14T18:19:02Z

Yeah, that’s a fair point. On Velocity, “disable” effectively means unloading the plugin, while “enable” loads it again. I’ll make that distinction clearer in the messages and documentation to avoid confusion. keep that?

I clarified that Velocity’s `disable` command fully unloads a plugin and `enable` loads it again, updating the command handling, messages, help output, and documentation accordingly.

…ling Renamed the experimental Velocity runtime to a Development Build. Renamed ExperimentalVelocityRuntime to VelocityDevelopmentRuntime. Updated startup warnings, diagnostics, documentation, and adapter messages. Added velocityCrashDumps for automatic crash dumps with unique IDs. Added velocityDevTestFunctions for protected development tools. Added /plugman dev status and /plugman dev crashdump. Added the plugman.dev permission. Added Velocity version, Java version, context, thread, OS, and stacktrace details to crash dumps. Restricted --force entirely to Velocity. Added runtime capability checks before parsing --force. Removed --force from Paper/Bukkit command help, usage text, messages, and documentation. Added Velocity-specific help entries for commands supporting --force. Added migration cleanup for old [--force] entries on non-Velocity platforms.

I restricted PlugManX proxy commands to the Velocity console so player commands can reach backend Paper servers, and added verbose development-mode logging for startup details, runtime operations, command execution, and diagnostics.

I separated Velocity from the shared Core and Paper assembly to prevent Paper reload issues. Paper now uses the stable PR Test-Account666#90 implementation, while Velocity is built separately.

I introduced a platform SPI for Velocity-specific behavior, removed the duplicated Core classes and Sonar exclusions, preserved the stable Paper behavior, and verified both builds with all tests passing.

I separated the Velocity console command alias from /plugman, allowing player commands and tab completion to pass through to Paper while keeping Velocity plugin management console-only.

Test-Account666 · 2026-07-17T13:57:01Z

Could you clarify the Java 25 requirement, please?
Are you specifically targeting/compiling against Java 25 instead of Java 21?

And is it just the Velocity module?

MrSimpleJS · 2026-07-17T14:29:11Z

Yes, the Java 25 requirement only applies to the Velocity module because it targets Velocity 4.0 internals. The Core, Paper, Bukkit, and Bungee modules remain on Java 21.

I aligned the Velocity Maven build with Java 25. Falling back to Java 21 would require dropping Velocity 4.0 support or publishing a separate Java 21 artifact for older Velocity versions.

Zoriot

Other than that works great so far. I had to make the changes to make it build locally.

added classloader-aware packet registry cleanup during plugin unload and failed-load rollback to prevent duplicate packet registrations. This currently works only on Velocity 4.0; I will test and add support for older Velocity versions later.

sonarqubecloud · 2026-07-27T14:18:23Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
1.6% Duplication on New Code

See analysis details on SonarQube Cloud

Add experimental Velocity plugin reload support

630b95a

I added experimental Velocity plugin loading, unloading, and reloading with runtime cleanup, platform-specific configuration and messages, startup warnings, detailed diagnostics, reload timings, and a separate versioned Velocity build.

MrSimpleJS mentioned this pull request Jul 14, 2026

Publish Velocity Build to Modrinth #94

Open

MrSimpleJS added 2 commits July 14, 2026 19:51

Improve Velocity unload safety and compatibility

3815b17

Velocity unload cleanup fault-tolerant, added version-specific runtime adapters, and introduced debug leak detection for remaining listeners, tasks, commands, and plugin threads.

Sonar issue

3022310

Clarify Velocity Enable and Disable Behavior

203b5e3

I clarified that Velocity’s `disable` command fully unloads a plugin and `enable` loads it again, updating the command handling, messages, help output, and documentation accordingly.

MrSimpleJS marked this pull request as draft July 14, 2026 18:51

MrSimpleJS added 11 commits July 14, 2026 21:00

Sonar issues

a02e997

added startup guidance for enabling debug logs

d2f1c94

Add cleanup warning

aa8790c

add more test options, rmvd useless stuff

c0bc6b3

fix memory leaks on velocity

d70a8ee

Separate Velocity from Core and Restore Paper Reload Stability

a756bc9

I separated Velocity from the shared Core and Paper assembly to prevent Paper reload issues. Paper now uses the stable PR Test-Account666#90 implementation, while Velocity is built separately.

Refactor Velocity integration using a platform SPI

c037a61

I introduced a platform SPI for Velocity-specific behavior, removed the duplicated Core classes and Sonar exclusions, preserved the stable Paper behavior, and verified both builds with all tests passing.

sonar

8fba636

Preserve Paper commands and tab completion behind Velocity

00d7143

I separated the Velocity console command alias from /plugman, allowing player commands and tab completion to pass through to Paper while keeping Velocity plugin management console-only.

i forgot to push: maven -> java 25

994831a

I aligned the Velocity Maven build with Java 25. Falling back to Java 21 would require dropping Velocity 4.0 support or publishing a separate Java 21 artifact for older Velocity versions.

Zoriot suggested changes Jul 17, 2026

View reviewed changes

Comment thread pom.xml

Comment thread plugman-velocity/pom.xml Outdated

Comment thread ...elocity/src/main/java/velocity/com/rylinaux/plugman/pluginmanager/VelocityPluginManager.java

MrSimpleJS added 6 commits July 18, 2026 08:16

Add Velocity 4.0 packet registry cleanup

66ca5e9

added classloader-aware packet registry cleanup during plugin unload and failed-load rollback to prevent duplicate packet registrations. This currently works only on Velocity 4.0; I will test and add support for older Velocity versions later.

enable older versions for packet registry cleanup

ef017b5

Track Velocity packet registry deltas during plugin loading

443e0aa

sonar

abbb28e

add 4.1.0 velocity

d308d7c

add capability check on plugman load

f4ef335

Fix Paper command synchronization batching

6a6ce84

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add experimental Velocity plugin reload support#95

Add experimental Velocity plugin reload support#95
MrSimpleJS wants to merge 23 commits into
Test-Account666:masterfrom
MrSimpleJS:Velocity

MrSimpleJS commented Jul 14, 2026 •

edited

Loading

Uh oh!

Test-Account666 commented Jul 14, 2026

Uh oh!

Test-Account666 commented Jul 14, 2026

Uh oh!

MrSimpleJS commented Jul 14, 2026

Uh oh!

Test-Account666 commented Jul 17, 2026 •

edited

Loading

Uh oh!

MrSimpleJS commented Jul 17, 2026

Uh oh!

Zoriot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sonarqubecloud Bot commented Jul 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

MrSimpleJS commented Jul 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Test-Account666 commented Jul 14, 2026

Uh oh!

Test-Account666 commented Jul 14, 2026

Uh oh!

MrSimpleJS commented Jul 14, 2026

Uh oh!

Test-Account666 commented Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

MrSimpleJS commented Jul 17, 2026

Uh oh!

Zoriot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sonarqubecloud Bot commented Jul 27, 2026

Quality Gate passed

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

MrSimpleJS commented Jul 14, 2026 •

edited

Loading

Test-Account666 commented Jul 17, 2026 •

edited

Loading