🌐 IPDynamic

Advanced IP Tracking & Alt Detection System for Minecraft Servers

Protect your server from ban evaders and manage player connections like never before.

📋 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:

Mode	Pattern	Example	IPs Affected
OP1	`x.x.x.*`	`192.168.1.*`	~256 IPs
OP2	`x.x..`	`192.168..`	~65,536 IPs

✅ 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

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

Requirements

Requirement	Version
Minecraft Server	1.17.x - 1.21.x
Server Software	Paper or Spigot
Java	17 or higher

🎮 Commands

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

📊 Information Commands

Command	Description
`/ipdy check <player>`	View complete player profile with IP history and alt accounts
`/ipdy history <player> [limit]`	View player's connection history
`/ipdy alts <player>`	List all detected alt accounts for a player
`/ipdy ip <address>`	Find all accounts that have used a specific IP
`/ipdy stats`	View plugin statistics

🚫 Ban Management

Command	Description
`/ipdy ban <op1\|op2> <ip> [reason] [duration]`	Ban an IP range
`/ipdy unban <pattern>`	Remove an IP ban
`/ipdy banlist`	View all active IP bans

Duration Examples:

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

✅ Whitelist Management

Command	Description
`/ipdy whitelist add <player> [reason]`	Add player to whitelist
`/ipdy whitelist remove <player>`	Remove player from whitelist
`/ipdy whitelist list`	View all whitelisted players

⚙️ Administration

Command	Description
`/ipdy reload`	Reload plugin configuration
`/ipdy help`	Display available commands

🔐 Permissions

Master Permission

Permission	Description	Default
`ipdynamic.*`	Full access to all commands	OP

Individual Permissions

Permission	Commands	Recommended For
`ipdynamic.check`	`/ipdy check`	Moderators
`ipdynamic.history`	`/ipdy history`	Moderators
`ipdynamic.alts`	`/ipdy alts`	Moderators
`ipdynamic.ip`	`/ipdy ip`	Moderators
`ipdynamic.ban`	`/ipdy ban`	Administrators
`ipdynamic.unban`	`/ipdy unban`	Administrators
`ipdynamic.banlist`	`/ipdy banlist`	Administrators
`ipdynamic.whitelist`	`/ipdy whitelist`	Administrators
`ipdynamic.stats`	`/ipdy stats`	Administrators
`ipdynamic.reload`	`/ipdy reload`	Administrators

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

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`	Pink
`&6`	Gold	`&e`	Yellow
`&7`	Gray	`&f`	White
`&l`	Bold	`&o`	Italic
`&n`	Underline	`&m`	~~Strike~~

🗄️ 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

Technology	Purpose
Kotlin 1.9	Primary language
MCCoroutine	Async operations on Bukkit
Paper API	Server integration
Adventure API	Modern text components
SQLite + JDBC	Data persistence
Mojang API	UUID verification

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

Server Version	Status
1.17.x	✅ Supported
1.18.x	✅ Supported
1.19.x	✅ Supported
1.20.x	✅ Supported
1.21.x	✅ Supported

📸 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

Does this plugin work with offline/cracked servers?

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.

Will my data be preserved after updating the plugin?

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

Does this plugin cause lag?

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

Can I use this with Spigot instead of Paper?

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

How accurate is the GeoIP detection?

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

Can players bypass IP bans with VPNs?

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.

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

💬 Support

📫 Issues: GitHub Issues
💭 Discussions: GitHub Discussions

Made with ❤️ by the IPDynamic Team

⬆️ Back to Top

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
README.md		README.md

SrCodexStudio/IPDynamic

Folders and files

Latest commit

History

Repository files navigation