Skip to main content

Platform Support

CocoAntiVPN is a true multi-platform plugin supporting all major Minecraft server and proxy software.

Supported Platforms​

PlatformSupportedJava VersionNotes
Bukkit✅Java 17+1.20+
Spigot✅Java 17+1.20+
Paper✅Java 17+1.20+ (Recommended)
Folia✅Java 17+Full async support
BungeeCord✅Java 17+Proxy-level protection
Velocity✅Java 17+Modern proxy support

Single Server Setup​

For standalone servers (no proxy), install CocoAntiVPN directly on your server.

Bukkit/Spigot/Paper​

  1. Download CocoAntiVPN.jar
  2. Place in plugins/ folder
  3. Start server
  4. Edit plugins/CocoAntiVPN/config.yml
  5. Run /antivpn reload

Folia​

CocoAntiVPN is Folia-supported with native async handling:

# plugin.yml
folia-supported: true

All VPN checks are synchronous with timeouts, making it safe for Folia's regionized multithreading.

Proxy Network Setup​

For networks using BungeeCord or Velocity, install CocoAntiVPN on the proxy only.

Why Proxy-Level?​

Installing on the proxy provides several advantages:

  • ✅ Single Point of Control - One config for all servers
  • ✅ Early Detection - Block before reaching any backend server
  • ✅ Better Performance - Check once, not per-server
  • ✅ Unified Bypass List - One bypass database for the network
  • ✅ Shared Blacklist - Blocked IPs can't access any server

BungeeCord Installation​

  1. Download CocoAntiVPN.jar
  2. Place in BungeeCord's plugins/ folder
  3. Restart BungeeCord
  4. Edit plugins/CocoAntiVPN/config.yml
  5. Run /antivpn reload from console

Folder Structure:

bungee/
├── plugins/
│   └── CocoAntiVPN/
│       ├── config.yml
│       └── data.db

Velocity Installation​

  1. Download CocoAntiVPN.jar
  2. Place in Velocity's plugins/ folder
  3. Restart Velocity
  4. Edit plugins/cocoantivpn/config.yml
  5. Run /antivpn reload from console

Folder Structure:

velocity/
├── plugins/
│   └── cocoantivpn/
│       ├── config.yml
│       └── data.db
Case Sensitivity

Velocity uses lowercase folder names (cocoantivpn), while BungeeCord uses the plugin name (CocoAntiVPN).

Architecture Details​

Core System​

CocoAntiVPN uses a shared core across all platforms:

┌─────────────────────────────────────┐
│           AntiVPNCore               │
├─────────────────────────────────────┤
│  • VPNChecker (API + Cache)         │
│  • SmoothRateLimiter                │
│  • DatabaseManager (SQLite)         │
│  • PlatformAdapter (Interface)      │
└─────────────────────────────────────┘
         ▲           ▲           ▲
         │           │           │
    ┌────┴───┐  ┌────┴───┐  ┌────┴───┐
    │ Bukkit │  │ Bungee │  │Velocity│
    └────────┘  └────────┘  └────────┘

Platform Components​

Each platform has specialized components:

ComponentBukkitBungeeCordVelocity
PluginBukkitPluginBungeePluginVelocityPlugin
CommandAntiVPNCommandBungeeCommandVelocityCommand
Login ListenerAsyncPlayerPreLoginEventPreLoginEventPreLoginEvent
Ping ListenerBukkitPingListenerBungeePingListenerVelocityPingListener
Netty InjectorBukkitNettyInjectorBungeeNettyInjectorVelocityNettyInjector

Database​

SQLite database stores:

  • Bypass List - Players who can skip VPN checks
  • Blacklist - IPs that were detected using VPN
-- Bypass table
CREATE TABLE bypass (player TEXT PRIMARY KEY COLLATE NOCASE)

-- Blacklist table  
CREATE TABLE blacklist (ip TEXT PRIMARY KEY, blocked_at INTEGER)

Performance Considerations​

Rate Limiting​

The smooth rate limiter prevents API abuse:

max-logins-per-second: 7

Uses a token bucket algorithm for smooth rate limiting without bursts.

Caching​

VPN check results are cached with Caffeine:

cache-minutes: 10

Cache specifications:

  • Maximum entries: 50,000
  • Eviction: Time-based (configurable)
  • High-performance Caffeine cache

API Timeouts​

VPN checks have built-in timeouts:

  • Connect timeout: 3 seconds
  • Request timeout: 2 seconds
  • Total check timeout: 5 seconds

If the API is slow, players are allowed to join (fail-open).

Troubleshooting​

Plugin Not Loading​

Check Java Version:

java -version

Must be Java 17 or higher.

Commands Not Working​

On Proxy:

  • Use console or ensure permissions plugin is installed
  • BungeeCord: Use LuckPerms BungeeCord version
  • Velocity: Use LuckPerms Velocity version

Players Not Being Checked​

  1. Ensure api-key is set correctly
  2. Check console for API errors
  3. Verify plugin is on proxy (for networks)
  4. Check if player is in bypass list
  5. Check if IP is timing out (5 second limit)

High Memory Usage​

Reduce cache size by lowering cache-minutes:

cache-minutes: 5