🌐 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.    ...

Releases: SrCodexStudio/IPDynamic

IPDynamic v1.0.0