IPViewer

🌐 Overview

IPViewer is a plugin that provides a simple way to view players' IP addresses, helping with server management and detecting ban evasion or multi-accounts.

Note: All technical settings and features described here are intended for the latest version of the plugin and may not be fully compatible with older versions.

🔍 Features

• View all players who have joined the server since the plugin was installed, along with their IP addresses and last seen time
• Filter and search player IPs easily
• Detect shared IPs across multiple accounts
• Helps track down ban evasion and suspicious activity

📜 Commands

Here are all the commands that can be used in the plugin:

• /ipv help - This command allows you to display all possible plugin commands
• /ipv reload - This command allows you to reload the plugin config
• /ipv script generate - Restore the bundled default script, overwriting plugins/IPViewer/scripts/default.js. This does not change the selected script
• /ipv script set <file> - Select an existing script, such as /ipv script set custom.js, and save its filename to script_geo_location. The filename must end in .js; paths are not accepted
• /ipv list [filters] - This command allows you to browse the list of players with optional filters

🪪 Filters for /ipv list

The /ipv list command supports flexible filters to help you search and organize player IP data. All filters can be used together in a single command.

Filter	Description
page:<number> or just <number>	Displays a specific results page (e.g., /ipv list 2 or /ipv list page:2)
player:<text>	Filters results by player name (supports partial matches and wildcards)
ip:<text>	Filters by IP address (supports partial matches and wildcards)
country:<text>	Filters by country name or code (e.g., country:"United States")
state:<text>	Filters by region or state (useful for more granular IP geolocation, e.g., state:"New York")
time:<duration>	Shows only players seen within a time range (e.g., time:24h, time:30m)

🧠 Wildcards

Filters that use text (player, ip, country, state) support SQL-style wildcards:

• % - Matches any sequence of characters
• _ - Matches a single character

You can also use spaces in filter values:

• Replace spaces with + - country:United+States
• Wrap the value in quotes - state:"New York"

When quotes are used, + characters are preserved as written.

📌 Example

/ipv list player:stev% ip:192.168.% time:7d page:3

This command shows page 3 of players whose names start with stev, IP starts with 192.168., and who have been seen in the last 7 days.

📁 Configuration

The config file is generated on first launch and modify it to adjust output formats or other plugin settings. View default config here.

All messages in the config use the MiniMessage format, which allows rich text formatting (colors, gradients, bold, etc.). You can preview and create formatted messages using the MiniMessage Viewer.

script_geo_location selects the JavaScript file used to resolve player geolocation:

script_geo_location: 'default.js'

The filename is resolved inside plugins/IPViewer/scripts/. Use a name such as custom.js, starting with a Latin letter, digit, underscore or hyphen; the remaining characters may also include dots. Directory paths and other extensions are not accepted. /ipv script set custom.js saves the selection immediately. If you edit the config manually, use /ipv reload to apply it.

🧩 Custom geolocation scripts

The scripting system lets administrators choose how player geolocation is obtained: use another provider, supply an API key through request headers, or transform the provider's response without rebuilding the plugin.

On startup, IPViewer checks whether plugins/IPViewer/scripts/default.js exists and copies the bundled default if it is missing. Existing files are left untouched, including empty files. /ipv script generate explicitly replaces this default file with the bundled version; it does not reset script_geo_location.

For each player join, the plugin reads the selected script and runs getGeoLocation(ip) through GraalJS on its asynchronous scheduler. Changes to a script apply on the next join, without a reload. The function must synchronously return an object with string fields country and state; a JSON string containing those fields is also accepted. IPViewer parses the result with Gson and uses it to create or update the player's profile. Script, HTTP or result-format errors are logged, and that lookup does not update the profile.

The returned JSON must have this structure (both fields are required and must contain strings):

{
  "country": "United States",
  "state": "California"
}

Return the equivalent JavaScript object, or use JSON.stringify({country: "United States", state: "California"}) to return a JSON string.

Embedded GraalJS provides JavaScript language features such as JSON.parse and JSON.stringify, but does not include browser or Node.js networking APIs. IPViewer supplies httpGet(url, headers?), so scripts do not need Java classes:

function getGeoLocation(ip) {
  const url = `https://ipwho.is/${encodeURIComponent(ip)}?fields=success,message,country,region`
  const data = JSON.parse(httpGet(url, {Accept: "application/json"}))

  if (data.success !== true)
    throw new Error("GeoIP service error: " + (data.message || "Unknown error"))

  if (typeof data.country !== "string" || typeof data.region !== "string")
    throw new Error("GeoIP service returned invalid country or region")

  return {
    country: data.country,
    state: data.region
  }
}

httpGet performs a synchronous HTTP/HTTPS GET and returns the response body as UTF-8 text. An optional object supplies string-valued headers, for example {Authorization: "Bearer YOUR_API_KEY"}. The connection and request timeouts are five seconds; network failures and non-2xx responses throw an error. Use ordinary functions; async functions and Promise results are not supported. Direct Java class access is disabled.

To add a provider, create a file such as plugins/IPViewer/scripts/custom.js, implement getGeoLocation(ip) with the response mapping for that provider, and select it with /ipv script set custom.js. Tab completion lists available .js files. The default provider uses HTTPS; consult the provider documentation for its current free-tier limits.

⚙️ Settings for developers or administrators

The plugin has permissions:

Permissions	Meaning	Default access
ipviewer.update_listener	Permission to receive update notifications	op
ipviewer.use	Permission to use commands	op
ipviewer.help	Permission to use command help	op
ipviewer.reload	Permission to use command reload	op
ipviewer.script	Permission to use command script	op
ipviewer.list	Permission to use command list	op

❗ Issues

Please leave messages about any errors you find here or on the Discord

💬 Social Media

• Page on Modrinth
• Page on GitHub
• Page on Discord

📊 Metrics