Configuration

CocoAntiVPN uses a single config.yml file for all settings. This guide explains each option in detail.

Default Configuration

prefix: "&8[&#00FFC1C&#00FFB7o&#00FFB7c&#00FFB7o&#00FFB7V&#00FFB7P&#00FFB7N&8]"

api-key: "PASTE-YOUR-API-KEY"
max-logins-per-second: 7
cache-minutes: 10

blocked-countries:
  - RU
  - CN
  - IR

discord-webhook-url: ""

kick-message: "&cVPN/Proxy usage is not allowed!"
rate-limit-kick-message: "&cToo many connection attempts, please try again later!"
staff-notify-message: "%prefix% &e{player} &7is using a VPN! &8(IP: {ip})"

command:
  no_permission: "%prefix% &cYou don't have permission for this!"
  usage: "%prefix% &7Usage: &b/antivpn help"
  enable_success: "%prefix% &aAntiVPN enabled."
  disable_success: "%prefix% &cAntiVPN disabled."
  reload_success: "%prefix% &aConfig reloaded."

  help: |
    %prefix% &b/antivpn enable &7- Enable protection
    %prefix% &b/antivpn disable &7- Disable protection
    %prefix% &b/antivpn reload &7- Reload configuration
    %prefix% &b/antivpn bypass &7- Manage bypass list

  bypass:
    usage: "%prefix% &7Usage: &b/antivpn bypass <add|remove|list> [...]"
    add_usage: "%prefix% &7Usage: &b/antivpn bypass add <player>"
    remove_usage: "%prefix% &7Usage: &b/antivpn bypass remove <player>"
    add_success: "%prefix% &a{player} added to bypass list."
    remove_success: "%prefix% &c{player} removed from bypass list."
    not_found: "%prefix% &c{player} is not in the bypass list."
    list: "%prefix% &7Bypasses: &f{list}"

  unban:
    usage: "%prefix% &7Usage: &b/antivpn unban <ip>"
    success: "%prefix% &aIP address &e{ip} &asuccessfully removed from blacklist!"
    not_found: "%prefix% &cIP address &e{ip} &cis not on the blacklist!"

# Blacklisted IP ping response
blacklist-ping:
  version-name: "IP Blacklisted"
  protocol-version: -1
  motd: "&cCould not connect to the server."
  max-players: 0
  online-players: 0
  player-sample: ""

Configuration Options

prefix

The prefix used in all plugin messages. Supports hex colors!

prefix: "&8[&#00FFC1C&#00FFB7o&#00FFB7c&#00FFB7o&#00FFB7V&#00FFB7P&#00FFB7N&8]"

Supports: Color codes (&c, &b, etc.) and hex colors (&#RRGGBB)

---

api-key

Your CocoStudios API key for VPN detection.

api-key: "YOUR-API-KEY-HERE"

Required

The plugin will not function without a valid API key. Contact CocoStudios to obtain one.

---

max-logins-per-second

Smooth rate limiting to prevent API abuse and server overload during bot attacks.

max-logins-per-second: 7

Recommended Values:

• Small servers (< 50 players): 5-10
• Medium servers (50-200 players): 10-15
• Large servers (200+ players): 15-25

Players exceeding this limit receive the rate-limit-kick-message.

---

cache-minutes

How long to cache VPN check results to reduce API calls.

cache-minutes: 10

Cache Details:

• Stores up to 50,000 IP results
• Uses Caffeine high-performance cache
• Reduces API calls for returning players

Recommended Values:

• High security: 5-10 minutes
• Normal use: 10-30 minutes
• Performance priority: 30-60 minutes

---

blocked-countries

List of countries to block, using ISO 3166-1 alpha-2 country codes.

blocked-countries:
  - RU  # Russia
  - CN  # China
  - IR  # Iran

Common Country Codes:

Code	Country
RU	Russia
CN	China
IR	Iran
KP	North Korea
VN	Vietnam
BR	Brazil
ID	Indonesia

Leave empty to disable country blocking:

blocked-countries: []

---

discord-webhook-url

Discord webhook URL for detection alerts.

discord-webhook-url: "https://discord.com/api/webhooks/..."

Leave empty to disable:

discord-webhook-url: ""

---

kick-message

Message shown to players kicked for using VPN/proxy.

kick-message: "&cVPN/Proxy usage is not allowed!"

---

rate-limit-kick-message

Message shown when rate limit is exceeded.

rate-limit-kick-message: "&cToo many connection attempts, please try again later!"

---

staff-notify-message

Message sent to staff with antivpn.notify permission.

staff-notify-message: "%prefix% &e{player} &7is using a VPN! &8(IP: {ip})"

Placeholders:

• {player} - The player's name
• {ip} - The player's IP address
• %prefix% - The plugin prefix

---

Blacklist Ping Settings

When a blacklisted IP tries to ping the server, they receive a custom response.

blacklist-ping:
  # Server version name shown in client
  version-name: "IP Blacklisted"
  
  # Protocol version (-1 = incompatible, shows "Can't connect")
  protocol-version: -1
  
  # MOTD message
  motd: "&cCould not connect to the server."
  
  # Max players shown (0 = hidden)
  max-players: 0
  
  # Online players shown
  online-players: 0
  
  # Player sample (hover text)
  player-sample: ""

This makes blacklisted IPs see a fake server status, discouraging reconnection attempts.

---

Command Messages

All command feedback messages are fully customizable:

command:
  no_permission: "%prefix% &cYou don't have permission for this!"
  usage: "%prefix% &7Usage: &b/antivpn help"
  enable_success: "%prefix% &aAntiVPN enabled."
  disable_success: "%prefix% &cAntiVPN disabled."
  reload_success: "%prefix% &aConfig reloaded."

Unban Messages

command:
  unban:
    usage: "%prefix% &7Usage: &b/antivpn unban <ip>"
    success: "%prefix% &aIP address &e{ip} &asuccessfully removed from blacklist!"
    not_found: "%prefix% &cIP address &e{ip} &cis not on the blacklist!"

Bypass Messages

command:
  bypass:
    usage: "%prefix% &7Usage: &b/antivpn bypass <add|remove|list> [...]"
    add_usage: "%prefix% &7Usage: &b/antivpn bypass add <player>"
    remove_usage: "%prefix% &7Usage: &b/antivpn bypass remove <player>"
    add_success: "%prefix% &a{player} added to bypass list."
    remove_success: "%prefix% &c{player} removed from bypass list."
    not_found: "%prefix% &c{player} is not in the bypass list."
    list: "%prefix% &7Bypasses: &f{list}"

---

Color Codes

CocoAntiVPN supports Minecraft color codes and hex colors:

Code	Color	Code	Color
&0	Black	&8	Dark Gray
&1	Dark Blue	&9	Blue
&2	Dark Green	&a	Green
&3	Dark Aqua	&b	Aqua
&4	Dark Red	&c	Red
&5	Dark Purple	&d	Light Purple
&6	Gold	&e	Yellow
&7	Gray	&f	White

Hex Colors: &#RRGGBB (e.g., &#00FFC1 for cyan)

Format Codes:

• &l - Bold
• &o - Italic
• &n - Underline
• &m - Strikethrough
• &k - Obfuscated
• &r - Reset