Advanced Synkai IP Limiter

A powerful Velocity proxy plugin that prevents multiple accounts from joining your server using the same IP address. Includes account binding, alt-account detection, and Discord webhook notifications.

Author: SynkaiMC
Version: 1.0.0
Website: https://synkaimc.in
Platform: Velocity Proxy

---

Features

• 🔒 IP-Based Player Limiting - Restrict concurrent connections per IP address
• 🔐 Account Binding - Bind player accounts to their IP address
• 🚫 Alt-Account Detection - Automatically detect and prevent alt accounts
• 🔑 Permission-Based Bypass - Allow ops and VIPs to bypass restrictions
• 📢 Customizable Messages - Color code support (&c, &4, etc.)
• 🔔 Discord Webhook Support - Get real-time notifications of violations
• ⚪ IP Whitelist - Configure trusted IPs with custom limits
• ⏰ Binding Expiration - Set binding duration (never, 1 week, 1 month)
• 🐛 Debug Mode - Enhanced logging for troubleshooting

---

Installation

1. Download the latest compiled JAR file from the build directory
2. Place it in your Velocity proxy's plugins/ directory
3. Restart your Velocity proxy server
4. Configuration file will be auto-generated at plugins/IPLimit/config.yml

---

Configuration

Edit plugins/IPLimit/config.yml to customize the plugin:

# IP Limit Configuration

# Max players allowed per IP (This limits concurrent sessions for the valid account)
max-players-per-ip: 1

# Permission to bypass checks (Ops usually have this)
bypass-permission: "iplimit.bypass"

# Message shown when kicked due to IP limit/Binding (Supports Color Codes like &c, &4)
kick-message: "&cYou are not allowed to join with this IP! 1 Account per IP limit."

# Message shown when kicked for using an Alt account
alt-kick-message: "&cAlt accounts are not allowed! This IP is bound to another account."

# Binding expiration policy (never, 1w, 1m)
binding-expiration: "never"

# Discord webhook settings (optional)
discord-webhook-enabled: false
discord-webhook-url: "webhookurl here"
discord-webhook-username: "Advanced Synkai IP limiter"
discord-webhook-embed-color: 16711680

# Whitelisted IPs (These IPs bypass all checks)
whitelisted-ips:
  - "192.168.1.1"
  - "10.0.0.1"

# Optional limits for whitelisted IPs (overrides normal max)
whitelisted-ip-limits:
  "127.0.0.1": 3

# Debug mode (prints more info to console)
debug: false

Configuration Options

Option	Type	Description	Default
max-players-per-ip	Integer	Maximum players allowed per IP	1
bypass-permission	String	Permission node to bypass checks	iplimit.bypass
kick-message	String	Message when player hit IP limit	Customizable
alt-kick-message	String	Message for alt accounts	Customizable
binding-expiration	String	Binding duration: never, 1w, 1m	never
discord-webhook-enabled	Boolean	Enable Discord notifications	false
discord-webhook-url	String	Discord webhook URL	webhookurl here
discord-webhook-username	String	Bot username for webhooks	Advanced Synkai IP limiter
discord-webhook-embed-color	Integer	Embed color (RGB decimal)	16711680
whitelisted-ips	List	IPs that bypass all checks	-
whitelisted-ip-limits	Map	Custom limits for specific IPs	-
debug	Boolean	Enable debug console output	false

---

Permissions

Permission	Description	Default
iplimit.bypass	Bypass IP limit and binding checks	Ops
iplimit.admin	Access admin commands	Ops

---

Commands

/iplimit [subcommand]

Subcommands

• info - Show player IP binding information
• reload - Reload configuration from disk
• unbind <player> - Remove IP binding for a player
• whitelist <ip> - Add IP to whitelist
• debug [on|off] - Toggle debug mode

---

Discord Webhook Setup

To get real-time notifications of IP violations:

1. Create a Discord webhook in your server settings
2. Copy the webhook URL
3. Edit config.yml:

   discord-webhook-enabled: true
   discord-webhook-url: "https://discord.com/api/webhooks/YOUR_WEBHOOK_ID/YOUR_WEBHOOK_TOKEN"
   

4. Customize the webhook username and embed color as desired
5. Reload the plugin with /iplimit reload

---

How It Works

1. First Connection - Player joins with their IP, account is bound to that IP
2. Same IP, Same Account - ✅ Allowed (logged in again)
3. Same IP, Different Account - ❌ Kicked (alt account detected)
4. Different IP, Same Account - ⚠️ Allowed (new IP, rebinding)
5. Whitelisted IP - ✅ Always allowed
6. Bypass Permission - ✅ Ops and VIPs bypass all checks

---

Features in Detail

Account Binding

Once a player joins, their account is bound to their IP address. This prevents other accounts from using the same IP.

Binding Expiration

Configure how long bindings remain active:

• never - Bindings are permanent
• 1w - Bindings expire after 1 week
• 1m - Bindings expire after 1 month

IP Whitelist

Add trusted IPs (proxy, testing, corporate networks) to bypass all checks:

whitelisted-ips:
  - "192.168.1.1"
  - "10.0.0.1"

Set custom limits for whitelisted IPs:

whitelisted-ip-limits:
  "127.0.0.1": 5  # Allow 5 players from localhost

Debug Mode

Enable debug logging to troubleshoot issues:

debug: true

Check console for detailed information about:

• Player connections
• IP bindings
• Permission checks
• Webhook requests

---

Troubleshooting

Players Getting Kicked Unexpectedly

1. Check the player's IP: /iplimit info <player>
2. Verify whitelisted IPs if needed
3. Check if player has iplimit.bypass permission
4. Enable debug mode for more info

Discord Webhook Not Working

1. Verify the webhook URL is correct
2. Check discord-webhook-enabled: true
3. Ensure the webhook hasn't been deleted from Discord
4. Check console for error messages with debug enabled

Config Not Updating

1. Use /iplimit reload to reload configuration
2. Ensure YAML formatting is valid
3. Check file permissions on config.yml

---

Building from Source

# Clone/download the repository
cd limitip

# Build with Gradle
./gradlew build

# JAR will be in build/libs/

---

License

See LICENSE file for details.

---

Support

For issues and feature requests, visit: https://synkaimc.in

Version: 1.0.0
Last Updated: February 2026