Experimental BanBridge 0.1.0

WHAT IS BANBRIDGE?

BanBridge is a distributed ban management system designed for Minecraft server networks. It enables real-time synchronization of player bans, statistics tracking, and presence monitoring across multiple game servers through a centralized backend service.

THE PROBLEM IT SOLVES

Running multiple Minecraft servers?

Problems without BanBridge:

• Player banned on Server A can still join Server B, C, D
• No cross-server player statistics
• Manual ban management across servers
• No audit trail of who banned whom and when
• Banned players laugh and go to another server

THE BANBRIDGE SOLUTION

• One ban = enforced on ALL servers instantly
• Unified player statistics across entire network
• Admin web dashboard for centralized moderation
• Offline-safe enforcement (works without internet)
• Complete audit logs with timestamps
• Automatic conflict resolution
• Real-time presence tracking

SYSTEM ARCHITECTURE

OVERVIEW

TWO-PART ARCHITECTURE

BACKEND (Centralized Service)

Runs independently on separate host/port

Features:

• Manages MySQL database
• Provides REST API endpoints
• Serves admin web dashboard
• Handles all ban logic
• Aggregates player statistics

Technologies:

• Java 17
• Embedded HTTP Server (JDK HttpServer)
• MySQL 5.7+ with HikariCP connection pooling
• Jackson for JSON
• SnakeYAML for configuration

CLIENT PLUGIN (Game Server)

Installed on each NukkitX game server

Features:

• Syncs bans periodically from backend
• Tracks player statistics
• Maintains local ban cache
• Updates player presence
• Communicates via HTTP REST

Technologies:

• Java 17
• NukkitX Server API
• OSHI for system metrics
• Jackson for JSON
• Exponential backoff retry logic

CLIENT PLUGIN FEATURES

PLAYER BAN PROTECTION

Ban Enforcement:

• Local ban cache checked at login
• Kicked immediately if banned
• Works offline (no internet required)
• Automatic cache sync every 10 seconds
• Support for temporary bans with expiration

Example Flow:
1. Admin bans player on Backend
2. Backend stores in MySQL
3. Plugin polls every 10 seconds
4. New ban appears in response
5. Local cache updates
6. Player joins ANY server → Kicked immediately

STATISTICS TRACKING

Automatic Collection:


Stored Data:

• Playtime (in seconds)
• Kill/Death count
• Last seen timestamp
• Online status
• Server metrics (CPU, memory, bandwidth)

EVENT HOOKS

PlayerLoginEvent

• Check ban cache
• Kick if banned
• Load player stats

PlayerQuitEvent

• Save session playtime
• Flush accumulated stats

PlayerDeathEvent

• Detect killer
• Record kill
• Record death

Periodic Tasks (configurable intervals)

• Poll bans from backend
• Flush stats to backend
• Update online presence
• Report server metrics

RESILIENCE

• Offline Mode: Works without backend (uses cached bans)
• Automatic Retry: Exponential backoff up to 4 attempts
• Connection Pooling: Efficient HTTP management
• Error Logging: Detailed console messages
• Data Persistence: Stats accumulated in memory, survives temporary outages

BACKEND FEATURES

REST API

Server API Endpoints:

Authentication:

• Token-based: X-Server-Key and X-Server-Token headers
• Per-server tokens stored in database
• Optional enforcement

ADMIN WEB DASHBOARD

Features:

• Secure login with session cookies (8-hour TTL)
• Player browser with stats filtering
• Ban management interface
• Statistics dashboard
• Audit log viewer
• Temporary ban support (hours/minutes)
• Search & filter capabilities

Pages:

• /admin/login - Authentication
• /admin/players - All players & stats
• /admin/bans - Ban list & history
• /admin/player?xuid=... - Player details & actions

DATA MANAGEMENT

Database Tables:

• players - Store player info (XUID, name, last seen, IP, HWID)
• player_stats - Aggregated stats (playtime, kills, deaths, KDR)
• bans - Ban records (reason, creator, expiration, revocation)
• audit_logs - Complete action history
• servers - Registered game servers & tokens
• presence - Current online status
• commands - Queue for server commands (future feature)
• metrics - Historical server metrics

Key Features:

• Automatic KDR calculation
• Ban status tracking (active/expired/revoked)
• Audit trail with timestamps
• Efficient indexing for performance
• Transaction support for data integrity

SECURITY

• Password Hashing: PBKDF2 (120,000 iterations)
• Session Management: In-memory with TTL
• SQL Injection Prevention: Prepared statements
• Token Authentication: Per-server tokens
• HTTPS Ready: Works behind reverse proxy

COMMUNICATION FLOW

BAN SYNCHRONIZATION

1. Admin bans player on Backend UI
2. Ban stored in MySQL
3. Plugin polls /api/server/bans/changes every 10 seconds
4. New ban appears in response
5. Plugin updates local BanCache
6. Player logs in on ANY server
7. Plugin checks BanCache
8. Player is kicked immediately

STATS UPLOAD

1. Player joins server
2. Stats accumulator records actions (playtime, kills, deaths)
3. Every 60 seconds: Stats flushed via POST /api/server/stats/batch
4. Backend receives batch with player deltas
5. Stats aggregated in database
6. Admin can view on dashboard

PRESENCE SYNC

1. Player logs in / logs out
2. PlayerLoginEvent / PlayerQuitEvent fires
3. Plugin updates in-memory presence list
4. Every 10 seconds: POST /api/server/presence/batch
5. Backend marks players online/offline
6. Available for queries & commands

SECURITY ARCHITECTURE

AUTHENTICATION LAYERS

Server-to-Backend:

• Token-based authentication
• X-Server-Key header identifies server
• X-Server-Token header authenticates request
• Tokens stored in backend database
• Optional enforcement via config

Admin-to-Backend:

• Cookie-based sessions
• Username/password login
• PBKDF2 password hashing
• 8-hour session TTL
• CSRF-safe operations

DATA PROTECTION

• In Transit: HTTP (ready for HTTPS via proxy)
• At Rest: MySQL with prepared statements
• In Memory: Spring-loaded sensitive data cleanup
• Audit Trail: All actions logged with user/timestamp
• Permissions: Role-based (admin/mod/viewer)

[hr]

PERFORMANCE CHARACTERISTICS

SCALABILITY

Tested Scenarios:

• 10,000+ banned players in cache
• 100+ concurrent players per server
• 50+ ban updates per minute
• 1000+ stat updates per flush

Optimizations:

• Connection pooling (HikariCP)
• Database indexing on hot columns
• Bulk INSERT/UPDATE operations
• In-memory accumulation before batch flush
• Efficient JSON serialization

NETWORK EFFICIENCY

Payload Sizes:

• Ban sync response: ~5KB (100 changes)
• Stats batch: ~10KB (100 players)
• Presence update: ~8KB (100 players)

Intervals (Configurable):

• Ban polling: 10 seconds (default)
• Stats flushing: 60 seconds (default)
• Presence updates: 10 seconds (default)
• Metrics reporting: 15 seconds (default)

Bandwidth Impact:

• Small (typically <1 Mbps for 100 servers)
• Backoff on errors prevents spamming
• Compressed JSON reduces payload

[hr]

USE CASES

MULTI-SERVER NETWORK
Ban a hacker on Survival → Instantly blocked on Creative, PvP, and Skyblock

ANTI-CHEAT INTEGRATION
Feed anti-cheat detections into BanBridge → All servers enforce

MODERATION TOOLS
Track player behavior across servers → Data-driven ban decisions

PLAYER ANALYTICS
Aggregate stats across network → Identify trends & popular players

NETWORK SECURITY
Coordinate bans across regional servers → Global player blacklist

[hr]

DATA COLLECTION

REQUIRED DATA

For Ban Enforcement:

• Player XUID (unique identifier)
• Ban reason
• Creation timestamp
• Expiration timestamp (if temporary)
• Revocation timestamp (if unbanned)

For Statistics:

• Player XUID & name
• Playtime (seconds)
• Kill count
• Death count
• Last seen timestamp

For Presence:

• Player XUID
• Online/offline status
• Server IP address
• Hardware ID (optional, for device bans)

AUDIT DATA

All administrative actions logged:

• Who banned/unbanned
• When action occurred
• Reason provided
• IP address of administrator

[hr]

INTEGRATION POINTS

GAME SERVER (NUKKITX)

Plugin integrates with:

• PlayerLoginEvent
• PlayerQuitEvent
• PlayerDeathEvent
• Periodic timers

BACKEND DATABASE (MYSQL)

Connects to standard MySQL with:

• Prepared statements
• Transactions
• Foreign keys
• Indexing

ADMIN DASHBOARD (WEB UI)

Pure HTML/CSS/JS (no external frameworks)
Works in any modern browser
Mobile-responsive (optional)

[hr]

TECHNOLOGY STACK

BACKEND


CLIENT PLUGIN


DATABASE


[hr]

DEPLOYMENT MODELS

SINGLE BACKEND, MULTIPLE SERVERS

1 Backend Instance → 1 MySQL Database → N Game Servers (unlimited)

Typical Setup:

• 1 Backend host (8-16GB RAM)
• 1 MySQL host (separate or same)
• 10-100 game server plugins

Recommended Hardware:

• Backend: 2 CPU cores, 4GB RAM, 500MB disk
• MySQL: 4 CPU cores, 8GB RAM, 10GB disk (scales with player count)

HIGH AVAILABILITY (Future)

Load Balancer → Backend 1, Backend 2, Backend 3 → Replicated MySQL

[hr]

KEY CAPABILITIES

REAL-TIME BAN ENFORCEMENT

• Ban syncing every 10 seconds
• Offline protection via local cache
• Temporary bans with expiration
• Revocation/unban support
• Broadcast to all servers instantly

COMPREHENSIVE STATISTICS

• Playtime tracking (per-minute granularity)
• Kill/death counting
• KDR calculation
• Historical aggregation
• Per-server & cross-server queries

ADMIN DASHBOARD

• Web-based management (no client software needed)
• Ban/unban players
• View player statistics
• Audit logs
• Session-based security
• Mobile-friendly (optional)

MONITORING & METRICS

• Server CPU/memory usage
• Network bandwidth tracking
• Connected player count
• Ban cache statistics
• API request metrics

[hr]

DESIGN PHILOSOPHY

RELIABILITY FIRST

• Works offline (cached bans enforce)
• Automatic retry on failures
• No single point of failure
• Data persistence

SIMPLICITY

• No complex frameworks
• Raw HTTP (no WebSocket complexity)
• Standard SQL
• YAML configuration

SCALABILITY

• Connection pooling
• Bulk operations
• Efficient indexing
• Configurable sync intervals

SECURITY

• Token authentication
• PBKDF2 hashing
• Session management
• Audit logging

[hr]

FUTURE ENHANCEMENTS

Planned Features:

• Command queue system (backend → plugins)
• IP-based bans
• Hardware ID bans
• Ban appeals system
• Discord integration
• Advanced analytics & dashboards
• Automatic rollback on false positives
• Multi-language support
• Database replication/HA
• Plugin auto-updates

[hr]

License: Proprietary - All rights reserved

Support: See Backend/README.md and Client/README.md for detailed documentation