🌐 Port Bridge

Automatic Port Forwarding for Minecraft Servers (Forge / NeoForge)

Port Bridge is a server-side Minecraft mod that automatically opens your server to the internet using router port forwarding logic.
No manual router configuration. No UPnP confusion. Just start the server and share the join address.

This mod is designed for self-hosted servers, home networks, and creators who want an easy way for friends to join without dealing with networking headaches.

---

✨ What Port Bridge Does

When your Minecraft server starts, Port Bridge will:

1. Detect your local server port

2. Discover your public IP address

3. Attempt to create a temporary port-forward mapping on your router (UPnP/NAT-PMP style logic)

4. Verify the mapping

5. Display the final public join address:

   • In the server console
   • As an OP broadcast message (configurable)

When the server stops, Port Bridge cleans up the port mapping so no unused forwards are left behind.

---

🚀 Key Features

🔌 Automatic Port Mapping

• Automatically forwards the Minecraft server port on startup
• No manual router login required
• Works entirely server-side

🔁 Lease / TTL Renewal

• Background task renews port mappings before they expire
• Prevents sudden disconnects during long server sessions
• Logs warnings if renewal fails

🧹 Clean Unmap on Shutdown

• Removes the port forward when the server stops
• Prevents leftover or “stuck” router rules

➕ Multiple Port Support

• Optionally forward additional ports:

  • RCON
  • Query
  • Web maps

• Fully configurable per port

🧠 Robust Diagnostics

• /portbridge diag command shows:

  • Router / gateway info
  • WAN service type
  • Mapping status
  • Last error details

• Helpful for debugging router compatibility

🧪 Dry-Run Mode

• Simulates port forwarding without actually changing router settings
• Perfect for testing and development
• Enable with advanced.dryRun = true

🌍 Profile / World-Based Configs

• Different port rules per server profile or world
• Useful for multi-instance setups

🔒 Network Safety Controls

• Restrict port forwarding attempts to specific local subnets
• Prevents accidental exposure on unsafe networks

💬 Custom Join Message Templates

• Fully customizable console + OP messages

• Use placeholders like:

  • {PUBLIC_IP}
  • {PORT}
  • {PROTOCOL}

• Example:

  🌍 Server is live!
  Join using: {PUBLIC_IP}:{PORT}
  

---

📜 Example Console Output

[Port Bridge] Server port detected: 25565
[Port Bridge] Public IP resolved: 103.xxx.xxx.xxx
[Port Bridge] Port mapping successful (TCP)
[Port Bridge] Share this address:
[Port Bridge] 103.xxx.xxx.xxx:25565

---

🧩 Supported Loaders

• ✅ Forge (server)
• ✅ NeoForge (server)
• ❌ Client-side not required

---

⚠️ Important Notes

• Router must support automatic port mapping protocols
• Some ISPs block inbound ports or use CGNAT
• If port mapping fails, the mod will not crash the server
• All actions are logged clearly for transparency

---

🛠️ Use Cases

• Hosting a server from home
• Playing with friends without manual port forwarding
• Testing servers on dynamic IP connections
• Temporary or short-lived servers

---

🔐 Security Philosophy

Port Bridge:

• Only opens ports while the server is running
• Cleans up on shutdown
• Never exposes more than what you configure
• Gives full control through config and commands

---

📦 Mod Name

Port Bridge
Bridging your local server to the world.