Documentation

Requirements

• Minecraft 1.21.X (Java Edition)
• Java 21 or newer
• Fabric API

Steps

1. Download the latest .jar for your Minecraft version from the releases page
2. Place the .jar file in your .minecraft/mods folder (Fabric API must also be in the mods folder)
3. Launch Minecraft with the Fabric loader profile
4. Press Z in-game to open the Archivist GUI, or configure API endpoints in the config file (see Configuration below)

The mod runs in the background once installed. It starts collecting data as soon as you join a server. Logs are saved locally to .minecraft/archivist/logs/ as JSON files.

Config file

The config file is located at .minecraft/archivist/config.json. It is created automatically on first launch with default values. You can edit it with a text editor or change most settings through the in-game GUI.

{
  "enabled": true,
  "logFolder": "archivist/logs",
  "autoHandleResourcePacks": true,
  "tutorial": true,
  "activeTheme": "Sunset",
  "showHudSummary": true,
  "showScanOverlay": true,
  "guiAnimations": true,
  "taskbarSlideAnimation": true,
  "passiveGuiDetection": true,
  "taskbarPosition": "bottom",
  "layoutMode": "dynamic",
  "sidebarPosition": "left",
  "sidebarOrder": [],
  "apiEndpoints": [],
  "autoUploadOnLog": false,
  "autoPushMinConfidence": 0.4
}

Key settings

• enabled -- master toggle for the mod
• logFolder -- where local JSON logs are saved (relative to .minecraft)
• autoHandleResourcePacks -- automatically accept mandatory and decline optional resource packs
• guiAnimations -- enable/disable GUI animations
• taskbarSlideAnimation -- animate taskbar transitions
• passiveGuiDetection -- analyze server GUI inventories as you open them to detect plugins
• activeTheme -- GUI color theme (20+ built-in themes like Dracula, Nord, Catppuccin, etc.)
• sidebarPosition -- sidebar alignment in dynamic layout mode ("left" or "right")
• apiEndpoints -- list of endpoints to sync data to (see API Key Setup below)
• autoUploadOnLog -- automatically push data to all endpoints when you disconnect
• autoPushMinConfidence -- minimum session confidence (0.0-1.0) required for auto-push; prevents uploading lobby/hub data

Archivist uses several methods to identify plugins. Each detection carries a confidence score (0-100%). When the same plugin is detected by multiple methods, the scores are merged for higher accuracy.

Command tree parsing

When you join a server, it sends a Brigadier command tree containing all registered commands. Archivist walks this tree looking for namespaced commands (e.g. worldguard:region) and matches non-namespaced commands against community-contributed rules and known plugin commands. Namespaced commands have 95% confidence; rule-matched commands have 70%.

Plugin channel namespaces

Servers send custom payload packets on named channels (e.g. worldedit:cui). The namespace portion identifies the plugin. These detections carry 80% confidence.

Registry data namespaces

During the configuration phase, the server sends registry entries that may include plugin namespaces. These carry 65% confidence.

Server brand string

The server brand packet identifies the server software (Paper, Spigot, Purpur, Velocity, BungeeCord, etc.) and sometimes its version. This is a 90% confidence detection.

GUI inventory analysis

When you open a server menu (chest GUI), the mod captures the inventory title, item names, lore text, and material types. These are matched against both rule-based patterns (from a user-editable rule database) and heuristic detection. Confidence is scaled by the session confidence score. You can create your own detection rules using the capture keybind (X).

Chat and tab list URL extraction

The mod scans chat messages, system messages, and tab list headers/footers for URLs and server addresses. It handles homoglyph obfuscation (Cyrillic lookalike characters, Unicode dots) and categorizes addresses as web URLs or game server addresses.

Lobby detection

A weighted multi-signal system determines whether you are on a real game server or a lobby/hub. It checks the command count and the presence of lobby-related commands (/server, /hub, /lobby), survival commands (/sethome, /tpa, /claim), adventure mode, and hotbar items (compasses, clocks, nether stars, player heads, and items with lobby-related display names). Deterministic rules force a classification when signals are strong enough (e.g. 10 or fewer commands with /server present forces lobby; 4+ survival commands forces real server). Proxy transfers are detected via multiple command trees and reset the evaluation. Lobby sessions are assigned low confidence so their data can be filtered out from uploads and detection results.

Keybinds

• Z -- Open/close the Archivist GUI (works on top of other screens too)
• X -- Start/cancel a GUI rule capture (while a server inventory is open)

The Archivist GUI

The GUI is a windowed interface with a taskbar, sidebar, and multiple panels. It shows the current server session info, detected plugins with confidence scores, an event log, and settings. It includes a built-in console for commands and supports 20+ color themes. The layout can be set to "dynamic" (sidebar + content) or "windows" (draggable windows) mode.

Console commands

Type these in the console panel inside the Archivist GUI:

• help -- list all available commands
• info -- show current server session details
• plugins -- list all detected plugins with detection methods
• scan -- re-run plugin detection on cached data
• export -- export the current session data
• db -- manage API endpoint sync (push, pull, status)
• theme -- change the GUI color theme
• clear -- clear the event log
• inspector -- inspect internal data
• diff -- compare plugin lists between sessions
• replay -- re-process the last captured GUI
• npc -- automation task controls

Scan progress overlay

When you join a server, a HUD overlay shows scan progress for about 60 seconds while the mod collects and processes data. This can be toggled off with the showScanOverlay config option.

Generating your key

1. Log in with your Discord account
2. Navigate to your Dashboard
3. Click Generate API Key
4. Copy the key immediately -- it will not be shown again

Adding an endpoint in the config

Add an entry to the apiEndpoints array in .minecraft/archivist/config.json. Header values are Base64-encoded in the config file for basic obfuscation. The mod's default pushEndpoint is /push. This site accepts data at both /api/push and /api/sync, so you can set the base URL to https://your-domain.com/api and leave the default push endpoint as-is:

{
  "apiEndpoints": [
    {
      "name": "Archivist Platform",
      "url": "https://your-domain.com/api",
      "method": "POST",
      "pushEndpoint": "/push",
      "downloadEndpoint": "/download",
      "resetEndpoint": "/reset",
      "adapterType": "REST",
      "authHeadersEncoded": {
        "X-API-Key": "<your key, Base64-encoded>"
      },
      "autoPush": false,
      "enabled": true
    }
  ]
}

Uploading data is optional. The mod works fully offline -- all data is saved locally as JSON logs. Configuring an API endpoint is only needed if you want to contribute to a shared database.

You can also configure endpoints through the Archivist GUI (press Z to open, then use the settings/database panel). The mod supports multiple endpoints simultaneously, including REST APIs, Discord bots, MongoDB, PostgreSQL, and SQLite adapters.

When autoPush is enabled on an endpoint (or autoUploadOnLog is true globally), data is automatically sent each time you disconnect from a server, subject to the confidence threshold. Failed pushes are queued and retried on the next successful push.

All API responses are JSON. Authenticated endpoints require either a session cookie (browser) or an X-API-Key header (mod / scripts).

Public Endpoints

curl https://your-domain.com/api/stats

{
  "total_servers": 1234,
  "total_scans": 56789,
  "total_plugins": 890,
  "total_contributors": 456
}

curl "https://your-domain.com/api/servers?search=hypixel&page=1&limit=20"

{
  "servers": [...],
  "total": 100,
  "page": 1,
  "limit": 20
}

curl https://your-domain.com/api/servers/abc-123

{
  "id": "abc-123",
  "ip": "mc.example.com",
  "port": 25565,
  "last_version": "1.21.1",
  ...
}

curl https://your-domain.com/api/servers/abc-123/plugins

{
  "plugins": [
    { "plugin_name": "EssentialsX", "first_seen": "...", "last_seen": "..." },
    ...
  ]
}

curl https://your-domain.com/api/servers/abc-123/history

{
  "scans": [
    { "id": "...", "scanned_at": "...", "version": "1.21.1", ... },
    ...
  ]
}

curl https://your-domain.com/api/servers/abc-123/worlds

{
  "worlds": [
    { "world_name": "world", "first_seen": "...", "last_seen": "..." },
    ...
  ]
}

curl "https://your-domain.com/api/rules?search=essentials&page=1"

{
  "rules": [
    { "id": "...", "plugin_id": "essentialsx", "plugin_name": "EssentialsX", "patterns": [...], "contributor_username": "user123", ... },
    ...
  ],
  "total": 42,
  "page": 1,
  "limit": 20
}

Authenticated Endpoints

curl -X POST https://your-domain.com/api/sync \
  -H "X-API-Key: arc_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"servers":[{"timestamp":"...","server_info":{"ip":"1.2.3.4","port":25565,"domain":"mc.example.com","brand":"Paper","version":"1.21.1","player_count":50},"plugins":[{"name":"EssentialsX"}],"gui_plugins":[],"detected_addresses":[],"detected_game_addresses":[],"worlds":[]}]}'

{
  "success": true,
  "server_id": "abc-123",
  "scan_id": "scan-456"
}

curl -X POST https://your-domain.com/api/push \
  -H "X-API-Key: arc_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d @scan_data.json

{
  "success": true,
  "server_id": "abc-123",
  "scan_id": "scan-456"
}

curl -X POST https://your-domain.com/api/upload \
  -H "X-API-Key: arc_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d @scan_data.json

{
  "success": true,
  "server_id": "abc-123",
  "scan_id": "scan-789"
}

curl https://your-domain.com/api/me \
  -H "Cookie: sb-access-token=..."

{
  "id": "user-123",
  "username": "agent_smith",
  "status": "active",
  "upload_count": 42,
  "created_at": "2025-01-01T00:00:00Z"
}

curl -X POST https://your-domain.com/api/me/api-key \
  -H "Cookie: sb-access-token=..."

{
  "key": "arc_live_abc123...",
  "message": "Save this key -- it won't be shown again."
}

curl -X POST https://your-domain.com/api/rules \
  -H "Cookie: sb-access-token=..." \
  -H "Content-Type: application/json" \
  -d '{"pluginId":"worldguard","pluginName":"WorldGuard","patterns":[...]}'

{
  "id": "...",
  "plugin_id": "worldguard",
  "plugin_name": "WorldGuard",
  "patterns": [...],
  "user_id": "user-123",
  ...
}

GUI rules are detection patterns used by the Archivist mod to identify plugins from inventory screens. Sharing rules helps the community detect more plugins automatically.

How to share a rule

1. Navigate to the GUI Rules page
2. Sign in if you are not already authenticated
3. Click the Upload Rule button
4. Upload a JSON file from your ~/.minecraft/archivist/rules/ folder or paste the JSON directly
5. Submit -- your rule will appear immediately for all users

Guidelines

• Use the official plugin name as listed on SpigotMC or Modrinth
• Include meaningful pattern labels that describe what the GUI screen looks like
• You can edit or delete your own rules within 24 hours of upload
• Maximum of 50 rules per user
• Downloaded rules go into ~/.minecraft/archivist/rules/

What data is stored

• Server IP addresses, ports, and domains
• Server brand, version, player counts, and detected plugin lists
• Detected URLs and game server addresses from chat
• World/dimension names
• Contributor account data: Discord ID (hashed internally), username, API key metadata
• Scan timestamps and source type (mod sync vs. web upload)

What is NOT stored or exposed

• Discord IDs are never exposed in public API responses. Contributor identity is represented by an internal UUID only.
• Player IP addresses or geolocation data
• Private server configurations or file system data
• Chat logs or private messages (only extracted URLs/addresses are stored)
• API keys are stored securely and never returned after initial generation

Server delisting

If you are a server operator and want your server removed from the Archivist database, you may request delisting. Contact us with proof of server ownership (e.g. DNS TXT record or a specific MOTD change) and we will remove the server and all associated scan data. Delisted servers will be blocked from future indexing.