IPDynamic

📋 Table of Contents

• ✨ Features
• 📥 Installation
• 🎮 Commands
• 🔐 Permissions
• ⚙️ Configuration
• 🗄️ Database
• 🔧 Technical Details
• 📸 Screenshots
• ❓ FAQ

✨ Features

🔍 IP Tracking

Track every player connection with detailed information including IP address, country, and timestamps.

👥 Alt Account Detection

Automatically detect alt accounts by analyzing shared IP addresses across your player database.

🚫 IP Range Banning

Powerful IP banning system with two operation modes:

✅ Whitelist System

Allow specific players to bypass IP bans with UUID and username verification via Mojang API.

🌍 GeoIP Integration

Automatic country detection for every connection using free GeoIP services.

💾 Persistent Storage

SQLite database with auto-adaptive schema - your data survives plugin updates seamlessly.

⚡ Async Operations

Built with Kotlin Coroutines for non-blocking database operations that won't lag your server.

🎨 Customizable Messages

Full message customization via messages.yml - translate or customize every plugin message.

🔒 Granular Permissions

Fine-grained permission system allowing you to give moderators exactly the access they need.

📥 Installation

1. Download the latest IPDynamic.jar from Releases
2. Place the JAR file in your server's plugins folder
3. Restart your server
4. Configure the plugin in plugins/IPDynamic/

Requirements

🎮 Commands

Base command: /ipdynamic (aliases: /ipdy, /ipd)

📊 Information Commands

🚫 Ban Management

Duration Examples:

• 30m - 30 minutes
• 12h - 12 hours
• 7d - 7 days
• 4w - 4 weeks
• No duration = Permanent ban

✅ Whitelist Management

⚙️ Administration

🔐 Permissions

Master Permission

Individual Permissions

Example Permission Setup

For Moderators (LuckPerms):

/lp group moderator permission set ipdynamic.check true
/lp group moderator permission set ipdynamic.history true
/lp group moderator permission set ipdynamic.alts true
/lp group moderator permission set ipdynamic.ip true

For Administrators:

/lp group admin permission set ipdynamic.* true

⚙️ Configuration

📁 messages.yml

Customize all plugin messages with full color code support:

# Prefix for all messages
prefix: "&b&lIPDynamic &8|"

# Ban screen shown to banned players
ban-screen:
  - "&c&l⚠ IP BANNED ⚠"
  - ""
  - "&7Your IP: &f{ip}"
  - "&7Matched Pattern: &c{pattern}"
  - "&7Reason: &f{reason}"
  - "&7Banned by: &f{banned_by}"
  - "&7Date: &f{banned_date}"
  - "&7Duration: &f{duration}"
  - ""
  - "&7Contact an administrator if you believe this is an error."

# Duration formats
duration:
  permanent: "&cPermanent"
  expired: "&aExpired"

# Command messages
messages:
  no-permission: "&cYou don't have permission to use this command."
  player-not-found: "&cPlayer not found in database."
  invalid-ip: "&cInvalid IP address format."
  # ... more messages

🎨 Color Codes

🗄️ Database

IPDynamic uses SQLite for data storage with automatic schema management.

Database Location

plugins/IPDynamic/ipdynamic.db

Tables Structure

📦 ipdynamic.db
├── 📋 players          - Player profiles and first connection data
├── 📋 connections      - Complete connection history log
├── 📋 ip_records       - IP address records per player
├── 📋 ip_bans          - Active IP range bans
└── 📋 whitelist        - Whitelisted players

Auto-Adaptive Schema

The database automatically adapts to plugin updates:

• ✅ Creates missing tables on startup
• ✅ Adds new columns without data loss
• ✅ Preserves all existing data during updates

🔧 Technical Details

Built With

Performance Optimizations

• 🚀 In-memory caching for bans and whitelist
• 🚀 Async database operations prevent server lag
• 🚀 WAL mode for SQLite concurrent access
• 🚀 Connection pooling for efficient queries
• 🚀 Lazy loading for player profiles

Version Compatibility

📸 Screenshots

Player Check

╭─────────────────────────────────────────╮
│  IPDynamic | Player Information         │
├─────────────────────────────────────────┤
│  Username: ExamplePlayer                │
│  UUID: 12345678-1234-1234-1234-1234567  │
│  First Connection: 01/01/2024 12:00:00  │
│  Total Connections: 150                 │
│                                         │
│  First IP                               │
│  Address: 192.168.1.100                 │
│  Country: United States                 │
│                                         │
│  IP History (3)                         │
│  - 192.168.1.100 (First)               │
│    Country: United States               │
│    Connections: 100                     │
│                                         │
│  Alt Accounts Detected (2)              │
│  - AltAccount1                          │
│    Shared IP: 192.168.1.100            │
│  - AltAccount2                          │
│    Shared IP: 10.0.0.50                │
╰─────────────────────────────────────────╯

Ban Screen

╭─────────────────────────────────────────╮
│           ⚠ IP BANNED ⚠                │
├─────────────────────────────────────────┤
│                                         │
│  Your IP: 192.168.1.100                 │
│  Matched Pattern: 192.168.1.*           │
│  Reason: Ban evasion                    │
│  Banned by: AdminName                   │
│  Date: 01/01/2024 15:30:00             │
│  Duration: 7d 0h                        │
│                                         │
│  Contact an administrator if you        │
│  believe this is an error.              │
│                                         │
╰─────────────────────────────────────────╯

❓ FAQ

Yes, IPDynamic works with both online and offline mode servers. The whitelist system uses both UUID and username verification to handle UUID differences between modes.

Yes! IPDynamic uses an auto-adaptive database schema that preserves all existing data while automatically adding new features.

No. All database operations are performed asynchronously using Kotlin Coroutines, ensuring zero impact on your server's TPS.

Yes, IPDynamic is compatible with both Paper and Spigot servers running version 1.17 or higher.

GeoIP accuracy depends on the free API services used. Country-level detection is generally 95%+ accurate, while city-level may vary.

Players can attempt to use VPNs, but you can ban VPN IP ranges using OP2 mode. Consider integrating with anti-VPN plugins for enhanced protection.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

💬 Support

• 📫 Issues: GitHub Issues
• 💭 Discussions: GitHub Discussions