# NatsBridge<\/p>\n
**NatsBridge** is a Java library that connects your **Spigot**, **Velocity**, or **BungeeCord** plugins to a **NATS** server \u2014 easily and efficiently.<\/p>\n
## \ud83d\ude80 Features<\/p>\n
* \u2705 Shared NATS **connection** across plugins
\n* \u2705 Supports **Spigot\/Paper**, **Velocity**, and **BungeeCord**
\n* \u2705 **High-performance Consumer API** for message handling
\n* \u2705 Clean API to **publish** messages
\n* \u2705 **Auto-reconnect** & error handling
\n* \u2705 **YAML configuration**
\n* \u2705 TLS & authentication support
\n* \u2705 Sync & async message handling<\/p>\n
## \ud83d\udce6 Setup<\/p>\n
1. **Download** the JAR:<\/p>\n
2. Drop it into your server\u2019s `\/plugins` folder.<\/p>\n
3. Start the server. A `nats-config.yml` file will be generated.<\/p>\n
4. Edit the config file and restart.<\/p>\n
## \u2699\ufe0f Usage Example<\/p>\n
### Using high-performance Consumer API<\/p>\n
“`java
\n\/\/ Sync consumer
\nNatsAPI api = BungeeCordNatsPlugin.getNatsAPI();
\napi.subscribeSubject(“game.player.join”, message -> {
\n String playerName = new String(message, StandardCharsets.UTF_8);
\n System.out.println(“Player joined: ” + playerName);
\n}, false);<\/p>\n
\/\/ Async consumer (byte[])
\napi.subscribeSubject(“game.chat”, message -> {
\n \/\/ Process chat message asynchronously
\n String chatMessage = new String(message, StandardCharsets.UTF_8);
\n broadcastToAllServers(chatMessage);
\n}, true);<\/p>\n
\/\/ Async consumer (String) – more convenient!
\napi.subscribeStringSubject(“game.chat”, chatMessage -> {
\n \/\/ Directly receive as String – no need for manual conversion
\n broadcastToAllServers(chatMessage);
\n}, true);
\n“`<\/p>\n
### Publish a message<\/p>\n
Firstly you need to know when the connection is established.
\nThere are 3 events for Velocity, Bungeecord and Spigot.
\n– VelocityNatsBridgeConnectedEvent
\n– BungeeNatsBridgeConnectedEvent
\n– SpigotNatsBridgeConnectedEvent<\/p>\n
Something like
\n“`java
\n@EventHandler
\npublic void onNatsBridgeConnected(SpigotNatsBridgeConnectedEvent event) {
\n \/\/Do something here
\n}
\n“`<\/p>\n
You just need to listen these events and the event is fire when the connection to NATS is up.<\/p>\n
“`java
\nBungeeCordNatsPlugin.getNatsAPI().publishString(“subject”, “Awesome message”);
\nBungeeCordNatsPlugin.getNatsAPI().publishRaw(“subject”, [something that is byte[]]);
\n“`<\/p>\n
## \ud83d\udcc2 Configuration (`nats-config.yml`)<\/p>\n
“`yaml
\nnats:
\n # List of NATS servers (can be a single server or a cluster)
\n servers:
\n – “nats:\/\/127.0.0.1:4222”
\n – “nats:\/\/nats-cluster.local:4222”<\/p>\n
# Authentication configuration (optional)
\n auth:
\n enabled: true
\n # Username\/password authentication
\n username: “user”
\n password: “pass”
\n # OR token authentication (if provided, username\/password are ignored)
\n # token: “your_token_here”<\/p>\n
# TLS configuration (optional)
\n tls:
\n enabled: false
\n # Paths to keystores (optional)
\n # keystore: “\/path\/to\/keystore.jks”
\n # keystore_password: “keystore_password”
\n # truststore: “\/path\/to\/truststore.jks”
\n # truststore_password: “truststore_password”<\/p>\n
# Reconnection configuration
\n reconnect:
\n # Maximum number of reconnection attempts (-1 = unlimited)
\n max_reconnects: -1
\n # Delay between reconnection attempts (in milliseconds)
\n reconnect_wait: 2000
\n # Connection timeout (in milliseconds)
\n connection_timeout: 5000
\n“`<\/p>\n
## \ud83d\udd27 Commands<\/p>\n
* `\/nats help` \u2013 Show help menu Permission required: `natsbridge.admin`<\/p>\n ## \ud83e\udde9 Gradle<\/p>\n “`gradle \/\/ Mandatory \/\/Select your platform ## \ud83e\udde9 Performance Considerations<\/p>\n The Consumer API approach offers several advantages:<\/p>\n 1. **No reflection overhead**: Native performance for message handling. ## \u2705 Requirements<\/p>\n * Java 21+ ## \ud83e\udd1d Contributing<\/p>\n 1. Fork this repo NATS messaging library for Minecraft servers<\/p>\n","protected":false},"featured_media":108827,"template":"","meta":{"_minecraft_slug":"natsbridge","_minecraft_project_id":"oIAQLwUD","_minecraft_author":"NhPro","_minecraft_license":"LicenseRef-Dual-License","_minecraft_downloads":13,"_minecraft_follows":0,"_minecraft_client_side":"unsupported","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"natsbridge.zip","_minecraft_size_bytes":610531,"_minecraft_version_count":1,"_minecraft_updated_at":"2026-05-15T22:58:47.683033Z","_minecraft_date_created":"2026-01-05T23:12:14.498971Z","_minecraft_date_modified":"2026-01-04T17:12:16.460990Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/natsbridge","_minecraft_icon_attachment_id":108827,"_minecraft_imported_at":"2026-06-06T07:11:37+00:00","_minecraft_import_hash":"5e84e373a897ad618ca5b3070bd135f4","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[124,894,125,873,126,127,128,129,92,985,992],"mod_loader":[130,895,131,132,133,134,986,993],"minecraft_version":[59,36,60,93,94,101,102,62,37,40,41,73,74,38,78,79,80,81,82],"class_list":["post-108826","mod","type-mod","status-publish","has-post-thumbnail","hentry","mod_category-bukkit","mod_category-bungeecord","mod_category-folia","mod_category-library","mod_category-management","mod_category-paper","mod_category-purpur","mod_category-spigot","mod_category-utility","mod_category-velocity","mod_category-waterfall","mod_loader-bukkit","mod_loader-bungeecord","mod_loader-folia","mod_loader-paper","mod_loader-purpur","mod_loader-spigot","mod_loader-velocity","mod_loader-waterfall","minecraft_version-1-20","minecraft_version-1-20-1","minecraft_version-1-20-2","minecraft_version-1-20-3","minecraft_version-1-20-4","minecraft_version-1-20-5","minecraft_version-1-20-6","minecraft_version-1-21","minecraft_version-1-21-1","minecraft_version-1-21-10","minecraft_version-1-21-11","minecraft_version-1-21-2","minecraft_version-1-21-3","minecraft_version-1-21-4","minecraft_version-1-21-5","minecraft_version-1-21-6","minecraft_version-1-21-7","minecraft_version-1-21-8","minecraft_version-1-21-9"],"yoast_head":"\n
\n* `\/nats status` \u2013 Check NATS connection status
\n* `\/nats test
\n* `\/nats reload` \u2013 Reload NATS configuration (planned)<\/p>\n
\nrepositories {
\n maven {
\n name = “natsbridge-repo”
\n url = uri(“https:\/\/repo.nhsoul.fr\/releases”)
\n }
\n}
\ndependencies {
\n \/\/Use the latest version<\/p>\n
\n compileOnly(“fr.nhsoul.natsbridge:core:1.0.0”)
\n compileOnly(“fr.nhsoul.natsbridge:common:1.0.0”)<\/p>\n
\n compileOnly(“fr.nhsoul.natsbridge:spigot:1.0.0”)
\n compileOnly(“fr.nhsoul.natsbridge:velocity:1.0.0”)
\n compileOnly(“fr.nhsoul.natsbridge:bungeecord:1.0.0”)
\n}
\n“`<\/p>\n
\n2. **Type safety**: Use of standard Java interfaces.
\n3. **Explicit control**: You control exactly when and how messages are processed.
\n4. **Platform integration**: Easy access to platform-specific APIs (Spigot, Velocity, BungeeCord).<\/p>\n
\n* A NATS server
\n* Minecraft 1.20+ server (Spigot, Velocity, or BungeeCord)<\/p>\n
\n2. Create a branch
\n3. Submit a PR \u2013 all contributions welcome!<\/p>\n","protected":false},"excerpt":{"rendered":"