Minecraft plugin EssentialsGeoIP

🔌 About EssentialsX GeoIP

EssentialsX GeoIP is a module for the EssentialsX plugin suite that performs local GeoIP lookups using the MaxMind GeoLite2 database. It integrates with EssentialsX to display an approximate location for players (for example in /whois and optionally to staff when a player joins).

🎯 Purpose

The module provides server staff with approximate geographic information derived from player IPs to aid moderation, logging, and basic location-awareness. Lookups are performed locally using the GeoLite2 database rather than by querying third-party lookup services for each request.

⚙️ Features

• Uses the MaxMind GeoLite2 database for IP-to-location lookups.
• Integrates with EssentialsX's /whois output to show approximate location.
• Optional: display a player's approximate location to staff when they join.
• Automatic database updates: the module downloads and refreshes the GeoLite2 database on a regular schedule (configured to update every 30 days by default).
• Permission nodes to control who can see or hide GeoIP results.

🧩 Who It Is For

This module is targeted at server administrators and moderation teams running EssentialsX who want approximate geographic data for moderation or logging purposes on Bukkit/Spigot/Paper servers.

🏗️ Example Use Cases

• Show staff an approximate country or city when inspecting a player with /whois.
• Log approximate origin regions for suspicious connections to assist moderation.
• Hide location display for opted-out players via permission.

🔐 Permissions

⚙️ Installation

📥 Setup

• Install the main EssentialsX plugin (the GeoIP module requires the matching EssentialsX core module).
• Download the EssentialsX GeoIP module JAR and place it in your server's plugins/ directory.
• Start the server once to generate the plugins/EssentialsGeoIP/config.yml file.
• Register for access to MaxMind's GeoLite2 database, generate a license key, and add that license key to the license-key setting in plugins/EssentialsGeoIP/config.yml.
• Restart the server. The module will download the GeoLite2 database using the provided key and keep it updated automatically.

📦 Dependencies

• EssentialsX (main module) — a matching version of the core EssentialsX plugin is required.

🧠 Technical Notes

• The module requires agreeing to and complying with the MaxMind GeoLite2 EULA; the database is approximate and must not be used to determine precise player locations.
• The database download/update behavior is part of the module and is configured to update on a monthly schedule; you must provide a valid MaxMind license key for automated updates.
• Shows data only where the EssentialsX core exposes /whois or join notifications; the module itself does not replace EssentialsX functionality.

🤝 When This Plugin Is Useful

If you run EssentialsX and need lightweight, local approximate location lookups for moderation or logging (while complying with MaxMind's license terms), EssentialsX GeoIP provides an integrated, auto-updating GeoLite2 solution.