Developer Reference
Build from Source
Section titled “Build from Source”Use a Java 25 JDK and the included Gradle wrapper:
./gradlew clean build javadocJarOn Windows PowerShell, use ./gradlew.bat clean build javadocJar. Sources target Java 25 and compile against Paper 1.21.11.
| Output | Purpose |
|---|---|
build/libs/port-bridge-<version>.jar | Deployable plugin with bundled runtime dependencies |
build/libs/port-bridge-<version>-plain.jar | Unshaded developer artifact |
build/libs/port-bridge-<version>-javadoc.jar | Packaged implementation reference |
build/docs/javadoc/ | Generated HTML documentation |
Install the deployable plugin JAR on the server. Browse the generated Javadocs for class and method contracts.
Service Ownership
Section titled “Service Ownership”| Class | Responsibility |
|---|---|
PortBridgePlugin | Configuration, tunnel initialization, command/listener registration, scheduled startup, and bStats lifecycle |
PlayerJoinListener | Delayed, permission-aware joining-player notification |
SettingsLoader | Listener-property resolution and validated immutable BridgeSettings |
Messages | Validated message catalog, immutable appearance values, and literal placeholders |
TunnelService | Serialized native-process lifecycle, route probes, retries, and state callbacks |
TunnelSnapshot | Immutable connection state and diagnostic values |
This release exposes its implementation reference rather than a separately versioned integration API. Read the source before depending on implementation types.
Thread Contract
Section titled “Thread Contract”SettingsLoader resolves Bukkit listener properties on the server thread. Plugin accessors are intended for enabled-plugin use on that thread.
TunnelService serializes native lifecycle and route probes on its worker. Process-output readers use virtual threads, and state callbacks marshal Bukkit interactions back to the server thread. Immutable TunnelSnapshot values can be retained across threads.
An address in a snapshot does not by itself establish a verified public route. Check the state and latency/health policy when interpreting connection results.
Messages and Lifecycle
Section titled “Messages and Lifecycle”Message formatting substitutes literal contextual values once. User-configured templates do not parse MiniMessage or legacy color codes; appearance colors are validated separately. See messages.yml.
Preserve reload validation, permission checks, and cancellation tokens when extending lifecycle behavior. Native processes, scheduled startup, and metrics are owned by the plugin lifecycle and must stop during disable.
Contribution and Validation
Section titled “Contribution and Validation”The build runs the unit suite. Check runtime behavior against the intended Paper versions when changing startup, commands, native process management, or thread callbacks. Follow the repository’s contribution guidelines, GPL headers, and class Javadocs.
Use the issue tracker for reproducible bugs. Include exact server and Java versions, reproduction steps, and relevant logs; follow SECURITY.md for private vulnerability reports.