Limiter Module

Limiter Module

The Limiter Module detects alt accounts based on IP addresses and enforces limits to prevent account abuse.

Module Status

Status: ✅ Active
Version: 1.1.6

🚀 Features

Core Functionality

• Alt Detection - Automatically detects accounts sharing the same IP address
• Alt Limits - Configurable maximum alt accounts per IP (default: 5)
• IP Limits - Limit different IPs per account (default: 3)
• Auto-Disconnect - Automatically disconnect players exceeding limits
• Staff Notifications - Real-time alerts when alt accounts join

Advanced Features

• Check on Join - Automatic checking when players join
• Cooldown System - Prevents spam checks (30 seconds cooldown)
• Custom Messages - Configurable disconnect messages
• IP Tracking - Complete IP history for players
• First/Last Seen - Track when accounts were first and last seen

📋 Commands

/alts <player>

View all alt accounts for a player.

Permission: zenith.limiter.alts

Parameters:

• player - Player name or UUID

Examples:

/alts Player123
/alts 12345678-1234-1234-1234-123456789012

/altlimit <player> [limit]

Set alt limit for a specific player.

Permission: zenith.limiter.alt_limits

Parameters:

• player - Player name or UUID
• limit - Maximum alt accounts allowed (optional)

Examples:

/altlimit Player123 5
/altlimit Player123 -1  # Unlimited

/iplimit <player> [limit]

Set IP limit for a specific player.

Permission: zenith.limiter.ip_limits

Parameters:

• player - Player name or UUID
• limit - Maximum different IPs allowed (optional)

Examples:

/iplimit Player123 3
/iplimit Player123 -1  # Unlimited

⚙️ Configuration

Module Settings

modules/limiter.yml

enabled: true

alt_detection:
  check_on_join: true
  check_cooldown: 30
  max_alts_shown: 5
  show_ip_address: true
  show_last_seen: true

alt_limits:
  enabled: true
  default_max_alts: -1  # -1 = unlimited, 0 = no alts, 1+ = specific limit
  disconnect_on_exceed: true
  disconnect_message:
    - "&#FF6B6B&lALT ACCOUNT LIMIT EXCEEDED"
    - "&#FFFFFFYou have reached your maximum allowed alt accounts."
    - "&#FFD93DCurrent alts: &#FFFFFF{current_alts}"
    - "&#FFD93DMaximum allowed: &#FFFFFF{max_alts}"

ip_limits:
  enabled: true
  default_max_ips: 3
  disconnect_on_exceed: true
  disconnect_message:
    - "&#FF6B6B&lIP LIMIT EXCEEDED"
    - "&#FFFFFFYou have used too many different IP addresses."

Notification Settings

notifications:
  permission: "zenith.limiter.alts"
  message: "&#FF6B6B[Alt Detection] &#FFFFFF{player} &#FFD93Dmay be an alt of: &#FFFFFF{alts}"
  sound: "BLOCK_NOTE_BLOCK_PLING"
  sound_volume: 0.5
  sound_pitch: 1.0

Message Variables

Alt Limit Messages

Variable	Description	Example
{player}	Player who was disconnected	Player123
{current_alts}	Current number of alt accounts	5
{max_alts}	Maximum allowed alt accounts	3
{ip}	IP address of the player	192.168.1.1

IP Limit Messages

Variable	Description	Example
{player}	Player who was disconnected	Player123
{current_ips}	Current number of different IPs	4
{max_ips}	Maximum allowed different IPs	3
{ip}	Current IP address	192.168.1.1
{ip_list}	List of all IPs used	192.168.1.1, 10.0.0.1

Notification Messages

Variable	Description	Example
{player}	Player who joined	Player123
{alt_count}	Number of alt accounts	3
{alts}	List of alt account names	Alt1, Alt2
{ip}	IP address (if enabled)	192.168.1.1

🔐 Permissions

Required Permissions

Permission	Description
zenith.limiter.alts	View alt accounts for players
zenith.limiter.bypass	Bypass alt detection and limits
zenith.limiter.alt_limits	Manage alt limits for players
zenith.limiter.ip_limits	Manage IP limits for players

Permission Examples

Full Access

permissions:
  - zenith.limiter.alts: true
  - zenith.limiter.alt_limits: true
  - zenith.limiter.ip_limits: true

What they can do:

• ✅ View alt accounts
• ✅ Set alt limits
• ✅ Set IP limits
• ✅ Receive notifications

Limited Access

permissions:
  - zenith.limiter.alts: true

What they can do:

• ✅ View alt accounts
• ❌ Set limits
• ❌ Manage IP limits

🎯 How It Works

Alt Detection Process

1. Player Joins - When a player joins the server
2. IP Check - System checks IP address against database
3. Alt Search - Finds all accounts with the same IP
4. Notification - Sends notification to staff if alts found
5. Limit Check - Verifies if alt limit is exceeded
6. Action - Disconnects player if limit exceeded

Limit Types

Alt Limit

• Limits how many accounts can share the same IP
• Example: Max 5 accounts per IP
• Prevents: One person with too many accounts

IP Limit

• Limits how many different IPs one account can use
• Example: Max 3 different IPs per account
• Prevents: Account sharing or VPN abuse

Configuration Examples

Strict Limits

alt_limits:
  default_max_alts: 2  # Only 2 accounts per IP

ip_limits:
  default_max_ips: 1  # Only 1 IP per account

Best for:

• High-risk servers
• Preventing alt abuse
• Strict security

Moderate Limits

alt_limits:
  default_max_alts: 5  # 5 accounts per IP

ip_limits:
  default_max_ips: 3  # 3 IPs per account

Best for:

• Most servers
• Balanced approach
• Family-friendly

Loose Limits

alt_limits:
  default_max_alts: -1  # No limit

ip_limits:
  default_max_ips: -1  # No limit

Best for:

• Trusted community
• VPN-friendly
• No restrictions

📊 Database Schema

Player IP Tracking

CREATE TABLE zn_players (
    uuid VARCHAR(36) PRIMARY KEY,
    username VARCHAR(16),
    ip_address VARCHAR(45),
    first_seen TIMESTAMP,
    last_seen TIMESTAMP,
    alt_limit INT DEFAULT -1,
    ip_limit INT DEFAULT -1
);

Alt Detection Query

-- Find all players with same IP
SELECT * FROM zn_players
WHERE ip_address = ?
AND uuid != ?
ORDER BY last_seen DESC;

🔔 Staff Notifications

Alt Detection Notifications

When an alt account joins, staff with appropriate permissions receive a notification.

Configuration:

notifications:
  enabled: true
  message: "&#FF6B6B[Alt Detection] &#FFFFFF{player} &#FFD93Dmay be an alt of: &#FFFFFF{alts}"

Sound Effects:

sound: "BLOCK_NOTE_BLOCK_PLING"
sound_volume: 0.5
sound_pitch: 1.0

Disable Notifications

To disable alt detection notifications:

notifications:
  message: ""  # Empty message = no notification

🛠️ Troubleshooting

Common Issues

Issue: Players getting disconnected without reason

• Check alt limit configuration
• Verify IP limit settings
• Check if player bypass is enabled

Issue: Alt detection not working

• Check if module is enabled
• Verify check_on_join is true
• Check database connection

Issue: No notifications received

• Check zenith.limiter.alts permission
• Verify notification message is not empty
• Check sound configuration

Issue: False positives

• Adjust alt limits to be more lenient
• Check if VPNs are being used
• Review IP tracking accuracy

Debug Mode

Enable debug mode for detailed logging:

debug:
  enabled: true
  console: true
  file: true

📈 Performance

Optimization Tips

• Cooldown System - Prevents excessive checks (30 seconds default)
• Efficient Queries - Indexed IP address column
• Caching - Results cached to reduce database load
• Async Operations - All checks are async

Monitoring

• Track alt detection frequency
• Monitor limit enforcement
• Review staff notifications
• Check for false positives

---

Need help with the Limiter Module? Join our Discord: https://discord.gg/2qCMn6KHj4